I stumbled across a need for this while I was doing some updates to my Google Desktop Plugin (YourMP).  If you’ve ever done any coding for GDS gadgets then you’ll know it uses JS.  Now my documenting was pretty poor so I wanted to tidy it up and went hunting for the usual format.

It wasn’t good.  Javascript source documentation is still in the dark ages as JS is still trying to be taken seriously not many people seem interested in documenting it nicely.

But I did eventually find a nice selection of 5…

JSDoc

This is based on the great JavaDoc and is a simple Perl script you run against your Javascript files and it outputs HTML, XML or XMI (UML diagram data).  I liked this a lot as a lot of the tags happen to coincide with the tags used in PHP (my ‘father’ language – please don’t hate me! ).  So it had virtually no learning curve and I would have settled if it wasn’t for my incessant curiosity…
Get JSDoc

HeaderDoc

If you’re a Mac fanboy I’ll probably lose you at this point as you go running off to use this Mac-made open source project.  Unfortunately its sh*t.  Although Mac made it they don’t make their documentation as nice and easy as their systems.  It reminded me of the heinous Amazon developer docs with excessive wordiness and fluff.  JSDoc above told me everything on a single page – done.  This spanned several pages going into minute detail on every possible usage.  It does cover a lot more languages like Obj-C, Java, C, etc but although its also based on JavaDoc I don’t like its unusual syntax which is just slightly different to JSDoc and the likes.  Why the “/*!” instead of “/**”?
It only exports HTML format too…
Get HeaderDoc (needs a login)

Natural Docs

This looks nice – both the output and the formatting of the source document tags.  It uses a more natural formatting rather than the usual tag method.  Although it does support JavaDoc style tags its much nicer to use the Natural way of doing it.  It supports a large number of languages such as C++, Python, Ruby, Java, etc.
Again it only exports in HTML or framed HTML formats but if thats all you’re after then its great.
Get Natural Docs

jGrouseDoc

This is onto a winner already with a name like that!  This project seems to understand the inherent difficulty of documenting Javascript code and so uses source comments as its only way of documenting.  Its heavily influenced by JavaDoc in its tags and output – which unfortunately isn’t great.  Does anyone else think the JavaDoc template looks utter tripe?  Thankfully it does come with other templates available and it is very easy to customise the output.  This is built very differently to the others as an ANT task.
Get jGrouseDoc

ScriptDoc

This is more of a specification and as such has no parsing utilities to output niceley formatted HTML.  Its an interesting idea but its s similar to JSDoc that you wonder why they’re even bothering.

Microsoft

Yes – they’ve been building XML-based JS documentation for their new VisualStudio when it comes out.  But as its Microsoft I’m sure we’ll all collectively not give a shit.