The Jass Doc is an encyclopedia-like source for information about Jass natives. The intended use is as a reference for understanding both the intended behavior and the bugs present for wc3 natives and blizzard.j functions.
This goal of this project is not to document every function and native but to add helpful comments for unclear functions, give notes about buggy functions and inform about other misc information.
Currently there's Jassbot - a JASS API search engine running that uses this as a database.
- Register a Github account, go to any file and click "Edit file".
- After you save changes, Github will ask you to create a Pull Request to submit your changes to us. Until then, you'll be editing your own copy of the files (you can't break anything)
- Send a message on Hiveworkshop forums
Do not worry about 100% "quality". Many functions do not have any descriptions at all. If you can't describe a function fully, adding little hints to a description would help too!
The format roughly follows Javadoc's approach: The documentation is written as code comments above a function.
The doc generator supports Markdown syntax (the same that's used on Discord, Reddit, Github etc.) Here's Reddit's simple explanation, though currently this code library is used.
Do note that the parser expects the @annotations after the general description.
For example a description of CripplePlayer:
/**
Reveals a player's remaining buildings to a force. The black mask over the
buildings will be removed as if the territory had been discovered
@note his function will not check whether the player has a town hall before revealing.
@param whichPlayer The player to reveal.
@param toWhichPlayers The players who will see whichPlayer's buildings.
@param flag If true, the buildings will be revealed. If false, the buildings
will not be revealed. Note that if you set it to false, it will not hide the buildings with a black mask.
*/
native CripplePlayer takes player whichPlayer, force toWhichPlayers, boolean flag returns nothing
You can start a description on the next line:
/**
@note one line. This word will be in **bold**
*/
/**
@note
Same as above, but on the next line, with a [link](http://example.com/function-discussion)
*/
Function's general description and explanation. This text must be at the start of the comment block.
Used to describe a function's variable. Add a short description, if the variable name doesn't properly explain its usage.
Describes buggy behaviour, when something doesn't work.
Adds your note that doesn't belong to a general description. You can recommend alternatives, explain something etc.
The function behaves like a mathematical f(x) = x+123 function: it doesn't change any state outside (no side-effects), only uses the arguments provided (only x here; no globals) and may return a new value, like x+123. Calling this function again and again would return the same value.
Adds a separate note, explaining that the values returned by this function are not synchronized between players by the game. I.e. each player has their own value; using this to affect the game world will cause a desync.
Lists events that the function interacts with. For example, GetEnteringUnit() only works together with EVENT_GAME_ENTER_REGION.
Describes when the function was introduced to the game. Many natives (game API) were added in 1.29.
Internal: @source-file, @source-code, @return-type
Proposed: @nosideeffect for functions without side-effects.
Remove anything you don't want to fill out / not applicable:
/**
GENERAL_DESCRIPTION
@param VARIABLE_1_NAME VARIABLE_1_EXPLANATION
@bug DESCRIBE_BUGGY_BEHAVIOUR_IF_ANY
@note ADD_YOUR_CUSTOM_NOTE
@async / @event EVENT_NAME / @patch PATCH_VERSION
*/
To build this project you need a somewhat recent GHC, cabal, gnu make and the
sqlite3 cli binary. To build jass.db all you have to do is to clone the
repository and run make inside it.
If you have a working nix/nixos installation you
can use the provided flake file and simply run nix build github:lep/jassdoc.
