Stan` Posted May 1, 2016 Report Share Posted May 1, 2016 (edited) 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 May 1, 2016 by stanislas69 5 Quote Link to comment Share on other sites More sharing options...
historic_bruno Posted May 7, 2016 Report Share Posted May 7, 2016 Not bad as a proof of concept! I think they need to be grouped somehow, to provide context, instead of one big list. Maybe based on paths for the broadest organization, so that AI, GUI, etc. are separated. 1 Quote Link to comment Share on other sites More sharing options...
Stan` Posted May 7, 2016 Author Report Share Posted May 7, 2016 Agreed, need to figure out if JSDOC allows that easily, or If you have to generate everything separately. Quote Link to comment Share on other sites More sharing options...
Teiresias Posted May 15, 2016 Report Share Posted May 15, 2016 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). Quote Link to comment Share on other sites More sharing options...
sanderd17 Posted May 15, 2016 Report Share Posted May 15, 2016 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. Quote Link to comment Share on other sites More sharing options...
Stan` Posted May 15, 2016 Author Report Share Posted May 15, 2016 @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 1 Quote Link to comment Share on other sites More sharing options...
Recommended Posts
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.