PDA

View Full Version : JSDoc template files



jamaljohnson
26 Oct 2006, 11:11 AM
jack, i searched around on the forum a bit and didn't find anything, but do you have your documentation tmpl files available? i'm a fan of your look and feel. thanx!

jack.slocum
26 Oct 2006, 7:45 PM
Sure. They aren't great though. I just zipped my jsdoc directory and threw it up here for you:

http://www.jackslocum.com/blog/jsdoc-dist.zip

jamaljohnson
27 Oct 2006, 4:02 AM
awesome, thanx jack

jamaljohnson
4 Dec 2006, 9:53 PM
ok, now that you have _really_ sick documentation, any chance of getting that distribution? ;)

brian.moeskau
4 Dec 2006, 10:13 PM
FYI, Jack's out this week, so you may want to bump this post again next week if you haven't heard from him by then.

coolhand27
31 Jan 2007, 2:35 PM
Looks like the link to the JSDoc tmpl link is dead. Any chance you can update it? I like to take a look at how you are doing your documentation so that I can implement something similar.

Thx

brian.moeskau
31 Jan 2007, 2:45 PM
I believe it was just a zipped version of the released docs: http://www.yui-ext.com/deploy/yui-ext/docs/

Jack has not yet released any of his newest doc parser source code or templates other than the deployed doc output.

JohnT
31 Jan 2007, 3:56 PM
Ok I am glad someone bumped this.

I have a question regarding documenting your code. I know there is no right and wrong way, but let's say I had the following function in an object, should I document this, or only real classes?

Example:



addAmmo : function(amt){
for(var i=0; i<amt; i++){
oConfig = {
tag : "img",
src : "images/shell.gif"
};
getEl("bulletHolder").createChild(oConfig);
}
oGun.bulletsLeft += amt;
}

tryanDLS
31 Jan 2007, 5:02 PM
I would document all the methods - not worth trying to decide for each fn whether it's worthy of doc - if it was important enough to make a fn, it should be doc'd.



/**
* Add a specified amount of ammo to the display and the gun.
* @private or @public
* @pararm {integer} amt The amount of ammo to add
*/

exo
15 May 2007, 2:48 AM
I would really really like to be able to generate the same kind of documentation as Ext uses. What sort of stuff will I need for that? JSdoc, templates?

brian.moeskau
15 May 2007, 5:22 AM
This is discussed elsewhere. We use an internal doc generator that may be made available at some point, but is not currently. If you simply want to replicate the style, you are free to look at the doc center CSS.

exo
15 May 2007, 1:23 PM
Internal eh, bummer :( It's not so much the css but more the structure overall that I like about the Ext docs. I do hope you guys release that generator one day :)

drew
13 Jul 2007, 6:58 AM
I've also been trying to hunt down something that will document javascript for me.

Has Jack released anything yet?

and if he hasn't, are their any alternatives, jsdoc doesn't seem to work (with standard tempaltes), obviously you guys are already aware of this, do I have any options?

JorisA
7 Aug 2007, 4:19 PM
http://www.jackslocum.com/blog/jsdoc-dist.zip
this link is not working anymore.
I'd like to compile the documentation for ext2.0 but I guess I need some templates.

brian.moeskau
7 Aug 2007, 9:01 PM
There is currently no way to compile the docs yourself. They used to be JSDoc compatible, but we've added lots of extensions to the JSDoc syntax to support things like events, config options, etc. in our docs. We use a custom parser to generate them and the parser is not currently available publicly. For now you'll have to use the docs in the source or wait for a public release.

JorisA
8 Aug 2007, 1:22 AM
Hmm so there is no documentation for 2.0?

brian.moeskau
8 Aug 2007, 1:29 AM
Hmm so there is no documentation for 2.0?

I didn't say that ;). I said that you'll have to use the docs in the source. All the docs originate in the source files, so you can read them there as well -- my point was that the doc center does not get generated until we do public releases.

With that said, at the moment many of the new 2.0 classes have not been documented yet. Look for documentation to be added throughout the source files as things progress.

JorisA
8 Aug 2007, 1:34 AM
Ok, thanks for the info.

christocracy
16 Jan 2008, 10:36 PM
I've been hacking away at the jsdoc parser for a few hours today, with some success.

anyone interested?

http://code.google.com/p/jsdoc-toolkit/

brian.moeskau
16 Jan 2008, 10:48 PM
Can you provide some more detail? You mean you're hacking it to read Ext-style comments?

christocracy
17 Jan 2008, 2:37 AM
see this thread: http://extjs.com/forum/showthread.php?p=110425#post110425

I posted a patch there, along with the files I edited.

I've got it rendering basic docs currently, scanning for "Ext.extend". it needs work but this is promising. I'd want to add parsing for @cfg, @event, etc.