jassdoc

[LeP]

jassdoc
It's still very early but it works.
My plan is to document natives and blizzard functions.
Not in a way that every function needs documentation but in a way to point out bugs, give useful misc infos and help with the lesser known functions.
Although i wouldn't mind documentation for every function.

For now i have taken comments from common.j, this thread about images and this thread.

I have written a programm which creates an sqlite database for all annotated functions so that everybody can use it.
Some usecases i could think of: tesh integration, a newer jass.sf.net.

It would be nice if you could write some docs. Some examples: 1, 2.

As i said it's still very early so i'm open about suggestions and stuff.

I attached the zip of the sqlite3-database generated from the docs.

 

[IcemanBo]

Maybe you can ask Bowser if has something to share - he initiated a similar thread: http://www.hiveworkshop.com/forums/lab-715/jasspedia-needs-your-feedback-264768/

 

[LeP]

Maybe you can ask Bowser if has something to share - he initiated a similar thread: http://www.hiveworkshop.com/forums/lab-715/jasspedia-needs-your-feedback-264768/

I took the liberty and already added these comments. Don't know where in the project i shoul give credits (readme, in the .j files, etc.).

 

[PurgeandFire]

Great idea! I'll try to contribute when I can. I tried something similar in the past (on this wiki) and have a decent amount of natives reasonably documented/tested.

How specific do you expect descriptions to be? You have support for @param, but I noticed it wasn't used too often just yet. On thehelper, it worked like this:

• When a post used [code=jass] tags, you could hover over natives to load a description.
• On hover, you would get a short description (i.e. in the wiki you specifically annotate desc vs. longdesc).
• On click, you could see the longdesc, parameter annotations, bugs, etc.

Also, can you explain @note, @pure, and @event?

 

[LeP]

Great idea! I'll try to contribute when I can. I tried something similar in the past (on this wiki) and have a decent amount of natives reasonably documented/tested.

How specific do you expect descriptions to be? You have support for @param, but I noticed it wasn't used too often just yet. On thehelper, it worked like this:

• When a post used [code=jass] tags, you could hover over natives to load a description.
• On hover, you would get a short description (i.e. in the wiki you specifically annotate desc vs. longdesc).
• On click, you could see the longdesc, parameter annotations, bugs, etc.

Also, can you explain @note, @pure, and @event?

I think most natives are somewhat reasonable so we don't need @param neccessarily.
You know something like "@param x The x coordinate the unit is created at" doesn't add too much value. But that doesn't mean it should not be added either.

@pure means that the function will always have the same return value for the same parameters.
Usefull for compiler-optimisations but also generally good to know. wc3 doesn't have many of these.

@nosideeffect would be a weaker @pure and would make more sense in wc3.
this list is a good starting point i think.

With @event i annotated all functions like GetEnteringUnit on which events they provide values.GetEnteringUnit for example is annotated with EVENT_GAME_ENTER_REGION because thats when that function makes sense.

I use @note for miscelanous infos. For example: i link to the StringHash sourcecode, or i link to a post that explains how to create an effect with z-pos.

For now i just used it whenever i felt like it. As i said it's very early.

I also thought about scraping thehelper.wiki but afaict they provide no api/easy access.

Also, you can generally add annotations as you like. Currently i only need special support for @param.

 

[PurgeandFire]

Thanks, that definitely cleared things up. And don't worry about scraping the wiki, I don't mind manually inputting it since I'd probably want to make revisions.

 

[LeP]

Thanks, that definitely cleared things up. And don't worry about scraping the wiki, I don't mind manually inputting it since I'd probably want to make revisions.

I see your wiki entries are very good. You can post your contributions in this thread or make a pull request on github. I will check both.
I also plan on building the sqlite-database regulary as i don't expect everybody to compile some haskell project just for the database.

 

[LeP]

I went through the list purgeandfire posted and added some comments to the repo. I also attached the sqlite-database to the first post.

 

[LeP]

With blizzard being active in wc3 land jassdoc can actually help fixing some bugs.
While probably not exhaustive we can get a quick look at buggy functions with a simple sql statement:

select fnname, value
from annotations
where anname == "bug"

Results in:

GetRandomSubGroupEnum|Not an even distribution. See <http://www.hiveworkshop.com/forums/l-715/g-275344>.
DestroyImage|May crash the game if an invalid image is used (null, before the first image is created).
SetImageRender|Does not work. Use SetImageRenderAlways instead.
PlayMusic|This native may cause a short lag spike as soon as the music starts. To circumvent this lag, stop the current music without fadeout before calling this function (`call StopMusic(false)`).
CameraSetupApplyWithZ|If a player pauses the game after the camerasetup has been applied, the z-offset of the game camera will change to the z-offset of the camerasetup for that player.
SetUnitScale|Only takes scaleX int account and uses scaleX for all three dimensions.
AddHeroXP|Adding negative value to experience will decrease it
by the stated value, but won't lower the level even if the experience value

after deduction is lower than the lower bound of the experience required to get

the stated level.

AddHeroXP|If the value will become lower than zero, the experience won't
be negative, instead of it it'll be equal

to 4294967296+(supposed_negative_experience_value) which actually proves 

that WarCraft III uses unsigned int type for storing experience points.

UnitDamagePoint|Has been known to cause crashes in battle.net
AddResourceAmount|If the value after adding negative amount will be less than zero, then it
will display negative resource amount, but if some peasant or peon will try to

gather resources from such a mine, he will bring back 0 gold and the mine will

be auto-destroyed.

UnitId2String|Always returns null after the game is loaded/if the game is a replay.
AbilityId|Not working correctly
AbilityId2String|Not working correctly
ResetUbersplat|Does nothing.
FinishUbersplat|Does nothing.
GroupEnumUnitsOfTypeCounted|Causes irregular behavior when used with large numbers
GroupEnumUnitsInRectCounted|Causes irregular behavior when used with large numbers
GroupEnumUnitsInRangeCounted|Causes irregular behavior when used with large numbers
GroupEnumUnitsInRangeOfLocCounted|Causes irregular behavior when used with large numbers
SetTerrainFog|Does nothing
AddSpellEffect|Does nothing.
AddSpellEffectLoc|Does nothing.
GetAbilityEffect|Does nothing.
GetAbilitySound|Does nothing.
MultiboardSetRowCount|It is only safe to change the row count by one. Use multiple calls for bigger values.
<http://www.hiveworkshop.com/forums/l-715/m-250775/>

<http://www.hiveworkshop.com/forums/t-269/w-234897/>

GetLocalizedString|Cannot assign it to a constant variable as it will crash the game.
`constaing string foo = GetLocalizedString("bar")`

I don't know how many of these could be fixed w/o breaking compability and from what i understand the new forum is for bugs introduced in the new patch so i just post it here.
If wanted one could always format this properly and make a good post in the patch discussion forum.
But with this i'll also bump this thread a bit

 

[Luashine]

I would like to motivate more people to contribute to a Jassdoc.
When I started poking at Warcraft 3, I had no idea about Jass or the game API. Yea that thing you call "natives" Much to my dismay there was no documentation created in the past 2 decades despite a flourishing and helpful community. I had to go through the same process many had gone before me: learning Jass, learning and finding out what even the basic functions did. Jass is straightforward for anyone who is "beyond the GUI Triggers" level, but without the explanation of the natives it's like knowing how to read but not understanding a single word. The fact that this is still the only way to learn and has been for such a long time, means one thing: thousands of manhours wasted and many discouraged in the process.

Let's say you find a function you don't know:

1. Check WC3Modding Jassdoc (TriggerSleepAction) or LeP's Jassdoc (DialogAddButton)
2. If it's not described yet: ask! I'm sure many people will know the answer
3. Contribute to the jassdoc. Help modders coming after you, searching is faster than asking. Describe what it does, if you can: add notes about corner cases and bugs.
   1. Contributing to WC3Modding it's easy, just like writing forum posts. Though I think moyack (admin) still has registration disabled due to spam. Ask him in Discord.
   2. LeP's jassdoc: It's on github, you can figure out how to edit files on the website if you're not a programmer. Creating an "issue" per documented function is fine too
   3. Just post here/message me. I will forward it.

Both jassdocs co-exist at the moment but my goal is to synchronize both automatically, because each website has its strengths. Up until now most of my contributions were on WC3Modding you can see for yourself.

---

Here's a list of incomplete functions:​

feel free to contribute!
IsUnitHidden
SetUnitAbilityLevel
EndGame, RemovePlayer
ForUnitsOfType has some quirks that are worth documenting
SetUnitColor can reset something?
KillSoundWhenDone - can cause desync?
GetPlayerTechResearched
BlzGetLocalSpecialEffectZ
TerrainDeformCrater
UnitItemInSlot

What else can be done? Create a forum section here, one thread per native, where people can submit their ideas and knowledge about an incomplete native.

 

[LeP]

Thanks for the big shoutout (and the big contribution)! Also have a look at Jassbot fuzzy search and documentation (which i guess i could have posted in here instead...) but personally i'm quite happy with the site (improvement suggestions always welcome though). I personally hoped the "modern" workflow with github would bring in some more contributors but documentation is tedious and time consuming. But i'm also happy scouting this thread/forum/other github projects.

 

[Jaccouille]

The first time I checked this repository years ago, I didn't really understand the point as I had no idea what to do with a SQL database containing documentation, now this Jassbot website looks useful to me, maybe you should add a link/description to the repository README.

 

[Bribe]

The integer fields that were added in 1.29 have problems which are outlined here:

List of non-working object data constants

The thread specifically addresses which object data related constants cannot be modified, work, or are problematic in some cases in the most recent patches (Not including the World Editor). This is a list in progress, so it may not yet include all the dysfunctional constants. Legend...

www.hiveworkshop.com

I also have an 11 year old thread which went over a number of problems:

[List] Common.j natives that do nothing/are useless/are broken

The goal of these lists is to compile a bunch of fail stuff. If you'd like to contribute, please don't bother with the uselessness of location functions like SetUnitPositionLoc, or wrappers such as GetDestructableX/Y instead of GetWidgetX/Y or GetEnteringUnit as opposed to GetTriggerUnit...

www.hiveworkshop.com

Also, this entire repository could likely be embedded:

Spell/Ability Damage Types and what they mean

For information on cross-referencing the terminology used below, please review: Wc3C.net - View Single Post - ATTACK_TYPE and DAMAGE TYPE testing. Big shout out to @Tasyen for helping me to fill out this list and also providing good feedback. Damage Type Used by Abilities Behavior Magic...

www.hiveworkshop.com

 

[LockonSt]

thanks for your tool

 

[LeP]

The integer fields that were added in 1.29 have problems which are outlined here:

List of non-working object data constants

The thread specifically addresses which object data related constants cannot be modified, work, or are problematic in some cases in the most recent patches (Not including the World Editor). This is a list in progress, so it may not yet include all the dysfunctional constants. Legend...

www.hiveworkshop.com

I also have an 11 year old thread which went over a number of problems:

[List] Common.j natives that do nothing/are useless/are broken

The goal of these lists is to compile a bunch of fail stuff. If you'd like to contribute, please don't bother with the uselessness of location functions like SetUnitPositionLoc, or wrappers such as GetDestructableX/Y instead of GetWidgetX/Y or GetEnteringUnit as opposed to GetTriggerUnit...

www.hiveworkshop.com

Also, this entire repository could likely be embedded:

Spell/Ability Damage Types and what they mean

For information on cross-referencing the terminology used below, please review: Wc3C.net - View Single Post - ATTACK_TYPE and DAMAGE TYPE testing. Big shout out to @Tasyen for helping me to fill out this list and also providing good feedback. Damage Type Used by Abilities Behavior Magic...

www.hiveworkshop.com

Do you have any native in mind? You can quickly check if something has documentation by either checking the website or using something like git grep -B 3 native-or-something-alike.
I can't really tell which threads i scavenged and what i took from them.
PRs welcome

 

[Bribe]

Do you have any native in mind? You can quickly check if something has documentation by either checking the website or using something like git grep -B 3 native-or-something-alike.
I can't really tell which threads i scavenged and what i took from them.
PRs welcome

I think I’ll just go over it over the weekend or something, when I get a chance. This also does not include the constants defined in common.j and blizzard.j, which help to understand the natives such as BlzSetUnitIntegerField. I needed to look those up on https://wc3modding.info/pages/jass-documentation-database/file/common.j/line/3354/

 

[LeP]

I think I’ll just go over it over the weekend or something, when I get a chance. This also does not include the constants defined in common.j and blizzard.j, which help to understand the natives such as BlzSetUnitIntegerField. I needed to look those up on https://wc3modding.info/pages/jass-documentation-database/file/common.j/line/3354/

That would be lovely indeed. I think my parser currently doesn't support annotating global variables but if you (or someone else) do the work i can always add it.
Done. Note though that you should not indent the docstring before a global variable. Instead do it like this

globals
/**
Some documentation...
*/
    constant boolean FALSE = false
endglobals

 

[Luashine]

I tried to find a function that'd remove a sound after playing:
Search - sound -> nothing?
I had to look further and a function exists: "native KillSoundWhenDone takes sound soundHandle returns nothing"
Search - takes sound -> here it is!

Why wasn't it shown for the "sound" query?

 

[LeP]

I tried to find a function that'd remove a sound after playing:
Search - sound -> nothing?
I had to look further and a function exists: "native KillSoundWhenDone takes sound soundHandle returns nothing"
Search - takes sound -> here it is!

Why wasn't it shown for the "sound" query?

It's just an artifact of how the fuzzy search works and how the API works.
The search engine ranks each native/function according to the user supplied query from 0 no match to 1 exact match. Now the API returns all natives with a score greater than 0.4 (afair) but only 25 in total (afair). I took this choice (low threshold, low count) to foster discoverability in a sense that the API might return some low "quality" but maybe interesting results.
Also my primary goal was to allow searching by signature and i only then added searching by name.
Because in my mind (coming from Haskell) you can often tell a lot more from the signature than from the name. For example an even better query would've been takes sound returns nothing.
Now if your use-case is mostly searching by name than the opposite might be better, that is high count, high threshold. And searching is hard. You can search for some fuzzy search implementations. They can become quite complex while mine is a linear scan with some bookkeeping.
All this text shouldn't discourage you from reporting this stuff though but i hope i could convey why it is how it is. I would encourage anybody to try out the type based search, even better in conjection with the name based search but I'm open for discussion.
I could try to tweak the parameters in such a way to rank KillSoundWhenDone higher on that particular query but then another query might return worse results.
I always intended this tool to not be a one-shot but an interactive tool. If your result isn't there try a different query or refine it (like with a parameter or a return type).

e:
I could go on forever as you might guess "searching" is a very deep hole.
Also you can also try stuff like this to quickly find stuff klsnd.

 

[Luashine]

Great explanation. Although it is weird not to have more/all results, the real problem is a lack of feedback to the user when there were more than 25 relevant entries, and in this case there were. There should be a footer with a helpful message when the limit is reached.

I think about regular search engines now, there the user decides what relevancy threshold to stop at. Every next search page shows ever more rubbish results. The user's threshold is when the user decides to close the page/refine the query after looking at results. Essentially, there's no artificial hard limit (of course there is, but usually by that time all results are random non-sense).

PS: To know what to search for, you must know beforehand what's out there. I still oftentimes look at blizzard/common.j

 

[LeP]

I think about regular search engines now, there the user decides what relevancy threshold to stop at. Every next search page shows ever more rubbish results. The user's threshold is when the user decides to close the page/refine the query after looking at results. Essentially, there's no artificial hard limit (of course there is, but usually by that time all results are random non-sense).

Very good point! I will see to either simply increase the amount returned or have pagination or whatever.

PS: To know what to search for, you must know beforehand what's out there. I still oftentimes look at blizzard/common.j

Well yes, that's exactly the point of type based search! You do know what you're searching for; at least partially. You know you're looking for a function that takes a sound so you type it. Then you assume that it either returns boolean for some status or just nothing so you test them.

 

[HerlySQR]

Hello, I found a bug with the function:

native ShowInterface                takes boolean flag, real fadeDuration returns nothing

If the parameter fadeDuration is not greater than 0 the unit portrait always appear empty, I made a pull request.

 

[Jaccouille]

How can I know which patch introduced a native so I can put appropriate annotation, e.g :

/**
@patch 1.32
*/
native BlzSetUnitFacingEx takes unit whichUnit, real facingAngle returns nothing

I'd like to PR "BlzShowUnitTeamGlow" but I don't know when it was added

 

[Luashine]

The only way is to compare the .j files of different versions. But don't bother about old functions, because this step is automatable.