Jump to content

JSDOC - Documentation


Recommended Posts

Currently only the c++ part has its documentation generated. Since there are some JSDOC comments on the Js part of the code as well I thought it would be nice to generate it as well. I therefore separated the js code (AI, GUI, RMGEN, Components, Globals, Helpers,...) from the public folder of A20 to generate the documentation.

Documentation was generated with JSDOC 3 using the node.js plugin
 

Since classes don't have the proper @class tag for now I added in attack.js so you can see what it can look like.

Here are the Documentation files (Open Index.html) : out.7z

And here are the files I used for the generation : 0adtest.7z

During the execution I got the following warnings : The unexpected identifiers ones are deprecated foreach (@elexis if you want to nuke those) and there are some errors with comments.

 

Spoiler

ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\AlertRaiser.js: Line 43: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\Formation.js: Line 100: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\FormationAttack.js: Line 28: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\Foundation.js: Line 174: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\GarrisonHolder.js: Line 69: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\Guard.js: Line 52: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\GuiInterface.js: Line 753: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\PlayerManager.js: Line 92: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\ProductionQueue.js: Line 320: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\ResourceGatherer.js: Line 96: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\StatisticsTracker.js: Line 205: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\tests\test_UnitAI.js: Line 298: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\Trader.js: Line 48: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\Trigger.js: Line 31: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\TriggerPoint.js: Line 77: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\components\UnitAI.js: Line 4646: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\gui\common\functions_utility.js: Line 39: Unexpected token for
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\gui\common\music.js: Line 111: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\gui\common\timer.js: Line 55: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\gui\manual\manual.js: Line 16: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\gui\savedgames\load.js: Line 22: Unexpected token for
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\gui\savedgames\save.js: Line 34: Unexpected token for
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\gui\session\input.js: Line 222: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\gui\session\unit_actions.js: Line 580: Unexpected identifier
ERROR: Unable to parse a tag's type expression for source file C:\Users\User\Desktop\0adtest\gui\structree\helper.js with tag title "param" and text "keypath The path to the value to be fetched. "Identity/GenericName"
               is equivalent to {"Identity":{"GenericName":"FOOBAR"}}": Invalid type expression ""Identity":{"GenericName":"FOOBAR"}": Expected "!", ".", "<", "=", "?", "[]", "|" or end of input but ":" found.
ERROR: Unable to parse a tag's type expression for source file C:\Users\User\Desktop\0adtest\gui\structree\helper.js with tag title "param" and text "keypath The path to the value to be fetched. "Identity/GenericName"
               is equivalent to {"Identity":{"GenericName":"FOOBAR"}}": Invalid type expression ""Identity":{"GenericName":"FOOBAR"}": Expected "!", ".", "<", "=", "?", "[]", "|" or end of input but ":" found.
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\gui\structree\structree.js: Line 22: Unexpected token for
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\helpers\Commands.js: Line 769: Unexpected token for
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\helpers\Damage.js: Line 22: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\helpers\FSM.js: Line 168: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\helpers\Setup.js: Line 14: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\helpers\Walls.js: Line 163: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\maps\random\rmgen\map.js: Line 270: Unexpected identifier
ERROR: Unable to parse C:\Users\User\Desktop\0adtest\maps\random\survivalofthefittest_triggers.js: Line 95: Unexpected identifier
ERROR: Unable to parse a tag's type expression for source file C:\Users\User\Desktop\0adtest\maps\scripts\TriggerHelper.js with tag title "return" and text "A list of new entities per origin like
{originId1: [entId1, entId2], originId2: [entId3, entId4], ...}": Invalid type expression "originId1: [entId1, entId2], originId2: [entId3, entId4], ...": Expected "$", "'", ".", "0", "\"", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "try", "typeof", "var", "void", "while", "with", "yield", Unicode letter number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter, Unicode uppercase letter or [1-9] but " " found.
ERROR: Unable to parse a tag's type expression for source file C:\Users\User\Desktop\0adtest\maps\scripts\TriggerHelper.js with tag title "return" and text "A list of new entities per origin like
{originId1: [entId1, entId2], originId2: [entId3, entId4], ...}": Invalid type expression "originId1: [entId1, entId2], originId2: [entId3, entId4], ...": Expected "$", "'", ".", "0", "\"", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "try", "typeof", "var", "void", "while", "with", "yield", Unicode letter number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter, Unicode uppercase letter or [1-9] but " " found.

 

Edited by stanislas69
  • Like 5
Link to comment
Share on other sites

  • 2 weeks later...

Hi stanislas69,

i have already tried introducing JsDoc some time ago with focus on the AIs and we had a discussion about it (see https://wildfiregames.com/forum/index.php?/topic/19488-proposal-enhance-common-api-with-documentation/).

At that time a big obstacle discovered was that JsDoc used a different JavaScript interpreter than 0AD itself: Rhino vs. SpiderMonkey. I don't know whether this has changed by now, but at that time it seemed like the 0AD JavaScript code was compatible only with 0AD itself, as SpiderMonkey seems to be the spearhead of JS development. Any separate tool using a different analyzer may introduce troubles.

Quoting mimo:

If it has JS compatibility issues which prevent us from using some JS features that we would want to use, that's a very strong point against its use.

What is your concept for handling this problem?

(Sorry for the less-than-optimal layout - my browser has severe problems with the new forum editor which i have not resolved yet).

Link to comment
Share on other sites

We're currently trying to move to the ES6 standard (just as spidermonkey is moving to the ES6 standard), which deprecates some spidermonkey-specific JS features (like for..each..in), but also offers more versatile code.

As other engines are also working towards the standard, using a documentation tool should become less of a problem.

Link to comment
Share on other sites

 

@Teiresias Well I didn't run into much trouble, put aside the lack of JSDOC comments. As I stated above adding those in the right places fixed the classes not appearing, though as @historic_bruno stated the design is not really optimal. I shall look for a good way to split the code like in namespaces. I know the new ES6 support classes(class(}), this might be something worth looking into. I don't know If one component could be translated from prototype to classe to see. I'll add that on my todo list.

Don't know if I answered your question.  =)
@sanderd17 AFAIK it works with ES6

  • Like 1
Link to comment
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

 Share

×
×
  • Create New...