…so you were a good programmer and you have added javadoc style comments in front of your javascript functions/classes/methods? Good boy! Now lets see what you can do with them. Solutions in order from worst to best (just to keep you entertained):

Javascript Documentor (JSD)
It is java based what would be super useful in ant scripts, however it expects me to write comments like:

1
2
3
 
/// <name>MyFunction</name>
/// <param name="param1">The first parameter passed in.</param>
/// <param name="param2">The second parameter passed in.</param>

Whaaaat?
1. Programmers will NEVER write that much metadata
2. Javadoc syntax is already de-facto standard, why invent a new one?
3. Javadoc syntax is already supported by many IDEs/editors
Next, please!

jGrouseDoc
Well, first of all, have you guys ever seen your page in Firefox? You would be disappointed for sure, as it gives a big blank page. Yes, i know you were trying to be smart with some ajax content loading, it just didnt work.
Anyway, after switching to IE, and downloading the tool, it turns out that it is java based, it can nicely be integrated with ant (it even comes with a fairly complex build script), but the only thing it recognized in my javascript file was… the filename itself. Hmm, thats good for a start, but lets move to the next one.

NaturalDocs
It is PERL based. It is meant to be a documentor for multiple languages, javascript not being among the fully supported ones. Lets give it a try though. Issue command. Read manual. Issue command. Read manual. Ah, ok. Issue command. Generation done. Hmm, plenty of files and directories, but not a single html. Apparently it couldnt digest my file. Next one!

JSDoc
Not to be mistaken with the JSD above! Because this is good:) It is PERL based, and will be happily running after you have downloaded the HTML-Template package. It magically recognized all my kinky objects and methods, and generated a classical jsdoc for them. Well done, i will stick with this one.

JSDoc Toolkit [UPDATE]
Just to confuse you more, there is this “toolkit” version. It seems to be the younger brother of the above mentioned JSDoc, but it is completely javascript based. Getting rid of the PERL dependency is great but it comes at a price. The javascript based processing is terribly slow, you have to see it for yourself if it is worth to switch. If you decided to switch, you can find a nice template here.

NOTE: On this wikipage you will find a bunch of other documentors, some of them are general, a few, apart from the above mentioned, are specific for javascript.

Happy documenting!

UPDATE: jGrouse website is now functional.

This is an archive post. It represents a point of view in the past. Facts might have changed, events might be interpreted differently as of today. Links might be broken.