Will pay if you help with documentation :)

[rich]

Ok so I really need to get the docs for Phaser sorted, but it's hard work not helped by the fact that Visual Studio won't generate the jsdoc block for me. However I know there are some IDEs that will (WebStorm seems to manage ok) but it's still going to take me hours and hours, time I could be spending coding.

 

So that is where this sort of crazy plan comes in. I would like if you guys could help me with docs. Now I don't expect you to write the descriptions for what everything in a class does - I'll do that part! But I just really need people to help go through the class files and add all the jsdoc blocks above each property and method. If you take a look at Collision.ts that's a good example of a class that I've mostly formatted properly:

 

/*** Checks for Line to Raw Line Segment intersection and returns the result in the IntersectResult object.* @param {Line} line The Line object to check* @param {Number} x1 The start x coordinate of the raw segment* @param {Number} y1 The start y coordinate of the raw segment* @param {Number} x2 The end x coordinate of the raw segment* @param {Number} y2 The end y coordinate of the raw segment* @param {IntersectResult} [output] An optional IntersectResult object to store the intersection values in. One is created if none given.* @returns {IntersectResult} An IntersectResult object containing the results of the intersection*/

 

What I need is for each class to have all of those jsdoc blocks in place (note the data types and [optional] blocks.parameters do.

 

I fully understand what a dull and boring task this is though, so I will cross your palms with silver if you help me out (i.e. pay you via PayPal).

 

There are approx. 70 classes in the project. I'll pay $10 per class documented. You must put jsdoc (following the example above) for every property and method in the TS file (not the JS output!).

 

So please help me out

 

HOW TO SEND ME A CLASS FILE:

 

If you want to use the script from Ezelia (posted below) to speed things up then by all means go ahead! Please upload the finished class files to this forum thread. The first person to upload a class gets the money for it, so I'd urge you to do a couple, post them, then do couple more (rather than do a load all together).

[Ezelia]

don't have time to write docs    ... but I took 30 minutes to write this little nodejs script that parses Typescript files and add jsdoc to the output.


there's still some indentation issues

 

 

    var fs = require('fs');    var file='AnimationManager.ts';        var data = fs.readFileSync(file, "utf8");                data = data.replace(/(public|private)\s([a-zA-Z0-9]+)\s*\((.+)\)([^{]*){/g, function() {        var original = arguments[0];        var params = arguments[3];        var ret = arguments[4];                var jsdoc = '\n/**\n';        jsdoc +='* \n';                                var ptokens = params.split(',');        for (var i=0; i<ptokens.length; i++)        {            var tokens = ptokens[i].split(':');            jsdoc +='* @param '+tokens[0]+'\n';        }                        if (ret.indexOf(':') >=0) ret = ret.replace(':', '');        else ret = null;        jsdoc +='* @returns '+ret+'\n';        jsdoc += '*/\n';                return jsdoc +original;            });    fs.writeFileSync(file+'.out', data); 

if it help I can adapt it to add/modify output

[Mike]

Well I'll be more than happy to help, but i Ezelia script make the grunt workof addin:

 

 

/*** * @param line * @param x1 * @param y1 * @param x2 * @param y2 * @param output * @returns {IntersectResult=}*/ 

 

 

I'm not sure that me or anybody beside you is going to write the write descriptions...

 

But if this is what you nee, as I seed I'll be happy to make some of the docs, let's say for the 5 Input Classes (Finger, Input, Keboard, Mouse, Touch)

 

So for the moment I'll wait for more info about did you tried and run Phaser trough Ezelia's script.

[Ezelia]

btw here is the output of my script for AnimationManager.ts (don't open it with notepad )

 

 

AnimationManager.ts.out.txt

[PixelPicoSean]

Wow I really like to help.

Well I guess you need document for params and methods, right?

Maybe I'll start from "infrastructure" classes.

BTW, script by Ezelia works very well for a start point.

[benny!]

Hey .. cool to see a script doing that work. Good work.

 

One question - wouldnt it make sense to add the type of the param, too ?

 

Nevertheless, if any help is still needed - I will try to help next week (no time over the weekend). I do not want any cash though of course.

[Chris]

Rich, your example doc-block is missing a few things like parameter types and optional indicators:

 

/** * Checks for Line to Raw Line Segment intersection and returns the result in the IntersectResult object. * @param {Line} line The Line object to check * @param {Number} x1 The start x coordinate of the raw segment * @param {Number} y1 The start y coordinate of the raw segment * @param {Number} x2 The end x coordinate of the raw segment * @param {Number} y2 The end y coordinate of the raw segment * @param {IntersectResult} [output] An optional IntersectResult object to store the intersection values in. One is created if none given. * @returns {IntersectResult} An IntersectResult object containing the results of the intersection */

*edit: oh, benny mentioned it already

[rich]

Interesting, the example I posted was from WebStorm, so I guess that is unable to work out data types! I'll edit my post above

[rich]

Ok I've updated the original post.

 

If you want to use the script from Ezelia to speed things up then by all means go ahead! Please upload the finished class files to this forum thread. The first person to upload a class gets the money for it, so I'd urge you to do 1, post it, then do another (rather than do a load all together).

[Chris]

Yeah, WebStorm/PHPStorm creates your JSdoc block automatically, but it isn't able to determine the argument types and if an argument is optional (and has a default value).
Whats also completely missing is jsDoc creation for events. You have to write those blocks on your own

On the other hand: WebStorm/PHPStorm interprets those doc tags correctly and will give you a heads up if you are passing wrong data-types.

[Ezelia]

here is an updated version of my script

 

this one include parameters types as Chris suggested and fixe indentation issues

 

I'll update it to use command line arguments instead of a hardcoded filename

 

 

copy the bellow script to a file named tsdoc.js :

usage example : 

$ node tsdoc.js AnimationManager.ts

or

$ node tsdoc.js AnimationManager.ts AnimationManager.ts.out

var fs = require('fs');var path = require('path');var infile, outfile;console.log('\n tsdoc - a jsdoc blocks generator for TypeScript files.\n'+' Author - Alaa-eddine KADDOURI\n'+' \n');var args = process.argv.slice(2);var scriptName = 'node '+path.basename(__filename);if (args.length == 0){        console.log(    ' usage      : '+scriptName+ ' inputfile <outputfile>\n\n'+    ' inputfile  : is the file you want to generate jsdoc for.\n'+    ' outputfile : (optional) the resulting file is sent to  outputfile, otherwise will overwrite inputfile .\n'+    ' \n'+    ' *Example :  '+scriptName+' myClass.ts');    process.exit();}infile = args[0];outfile = args[1] || infile;console.log(infile, ' => ', outfile);var data = fs.readFileSync(infile, 'utf-8');//parse function's signaturedata = data.replace(/([\n\r\s]*)(public|private)\s([a-zA-Z0-9]+)\s*\((.+)\)([^{]*){/g, function() {    var original = arguments[0].replace(/(\r\n|\n|\r)/gm,""); //clean CR LF    var indent = arguments[1].replace(/(\r\n|\n|\r)/gm,""); //get original indentation    var params = arguments[4];    var ret = arguments[5];        //parse function's parameters    params = params.replace(/([0-9a-zA-Z]+)\s*:\s*([0-9a-zA-Z\[\]]+)\s*([^,]*)([\,]{0,1})/g, function() {        var name = arguments[1];        var type = arguments[2];        return indent+'* @param '+name + ' {'+type+'} \n';            });          //returned type    ret = (ret.indexOf(':') >=0) ? ret.replace(':', '') : undefined;            //build jsdoc         var jsdoc = '\n\n '    jsdoc += indent+'/**\n';    jsdoc += indent+' * \n';            jsdoc += ' '+params;            if (ret) jsdoc += indent+' * @returns {'+ret+'}\n';    jsdoc += indent+' */\n';            return jsdoc+original;    });fs.writeFileSync(outfile, data); 

 

 

 

output example :

 

 

         /**         *         * @param {string} name         * @param {any[]} frames         * @param {number} frameRate         * @param {bool} loop         * @param {bool} useNumericIndex         * @returns {null}         */        public add(name: string, frames: any[] = null, frameRate: number = 60, loop: bool = false, useNumericIndex: bool = true) {            if (this._frameData == null)            {                return;            }         ... 

 

[Edit] : updated the script to allow passing intput/output files as command line arguments

[PixelPicoSean]

Why borther pasting code here instead of using git?

 

Well I've almost finish 18 classes till now. I'm going to post them soon after final editing.

[Ezelia]

I have no access to github right now ... I posted the script here to help people if they want to use it.

 

will create a git repo tonight

[PixelPicoSean]

root:

• AnimationManage,  Cache, CameraManager, DynamicTexture, FXManager.
• Game, Group, Motion, SoundManager, Stage.
• State, Time, TweenManager, World.

gameobject:

• Emitter, GameObject, GeomSprite, ScrollRegion, ScrollZone.
• Sprite, Tilemap.

geom:

• IntersectResult, Line, MicroPoint, Point, Rectangle.

system:

• Camera, Device, QuadTree, Sound, StageScaleMode.
• Tile, TilemapLayer, Tween.

system/animation:

• Animation, AnimationLoader, Frame, FrameData.

system/input:

• Finger, Inout, Keyboard, Mouse, Touch.

system/screens:

• BootScreen, PauseScreen.

[update]:

  All files can be found at my folked github repo: 

https://github.com/pixelpicosean/phaser

 

[PixelPicoSean]

I have no access to github right now ... I posted the script here to help people if they want to use it.

 

will create a git repo tonight

Sorry, I didn't refer to the script 

Actually wonder if it's better to upload final classes here.

[rich]

You can zip them all together and upload the zip file here, or you can use git if you want but POST HERE TO SAY WHAT FILES YOU'VE DONE! As it's the only way other people will understand which classes to ignore

[rich]

Nice one PixelPicoSean! Just to say that I fly out to LA in a few hours time, so won't be able to check the forum/emails until I'm back on Thursday - so please don't think I'm ignoring you, but do please carry on uploading classes

[rich]

I'm un-sticking this now because PicoSean provided descriptions for virtually every single class file, all now committed in the 096 branch. Nice one!

[retrogamer4ever]

So I tried running jsdoc on phaser.js file for 096 and it kept puking because some of the way things were documented were not correct. So I started going in and refactoring the docs and it slowly began to work... My question is how should I go about doing this? 

 

I am not familiar with typescript and just been using javascript, I am assuming all the typescript files are documented and then you use grunt to build it all and generate the phaser.js file? If I were to start refactoring the docs is that where I would start? 

[rich]

I've tried running jsdoc on the js files too and it definitely didn't like it. I wasn't sure how much of it could actually be fixed or not. But the comments in the JS are the exact same comments as placed in the TS files. So ideally if you wanted to help do this then I guess make a tweak to the phaser.js - see if jsdoc liked it, and then duplicate that in the correct TS file.

 

Sounds like a lot of work though? Might be easier to just post some examples up here of things that break jsdoc so I can fix them direct in the the TS?

[retrogamer4ever]

Awesome! Will do :-D I'll make note of the changes and post if I can get the phaser.js file to build with it. It may end up being a lot of work but I desperately need some docs, sadly my IDE can't auto-complete the deeply nested (in all of the function(), and all on the anonymous function calls) docs so id much rather have some sort of live docs working so I can look at that.

[retrogamer4ever]

Good news! I got the jsdoc working with the phaser.js file :-) Here is a link to the altered file and the docs it generates (it's 096, you can run a diff on it to see changes). http://www.gamedevradio.net/docChanges.zip It didn't turn out exactly as helpful as I thought, haha... But still something I guess. Since the changes were pretty few and not that much I may go through when I have some time and change the typescript files. 

 

The biggest issues I found was these 

 

1. documenting arrays like this {string[]|number[]} it doesn't like, just do {Array<string>|Array<number>}

2. documenting a variable with the @type doesn't like having description after stating the type. So "@type {number}" is the right way and doing it "@type {number} this is what it does" Makes jsdoc go nuts. Although seems that could just be a bug in jsdoc, fix is just move the description to the top.

3. Just a few empty doc blocks and broken doc tags :-)

 

 

Here is the link I used to know what jsdoc looks for http://usejsdoc.org/ 

 

Hope that helps :-)

[rich]

Nice one, I'll download it and check out it Not having a description after the parameter is strange. I'm sure jsdoc must support that. Will take a look and see!

[PixelPicoSean]

Good news! I got the jsdoc working with the phaser.js file :-) Here is a link to the altered file and the docs it generates (it's 096, you can run a diff on it to see changes). http://www.gamedevradio.net/docChanges.zip It didn't turn out exactly as helpful as I thought, haha... But still something I guess. Since the changes were pretty few and not that much I may go through when I have some time and change the typescript files. 

 

The biggest issues I found was these 

 

1. documenting arrays like this {string[]|number[]} it doesn't like, just do {Array<string>|Array<number>}

2. documenting a variable with the @type doesn't like having description after stating the type. So "@type {number}" is the right way and doing it "@type {number} this is what it does" Makes jsdoc go nuts. Although seems that could just be a bug in jsdoc, fix is just move the description to the top.

3. Just a few empty doc blocks and broken doc tags :-)

 

 

Here is the link I used to know what jsdoc looks for http://usejsdoc.org/ 

 

Hope that helps :-)

Thanks man, I'm also going to help fix that. Sorry for those issues with doc, I did not test them before.

[retrogamer4ever]

No reason to apologize buddy, we are all in this together, doing documentation isn't an easy task. So much of it you have to include in a certain way.

 

Just trying to do my part and help make it even more awesome then it already is! :-)