jsDoc - a javadoc implementation for javascript
Ok, so I’ve finished as much digging on this subject as I plan on doing (mostly because the pickings seem to be rather slim). Here’s jsDoc - a javadoc implementation for javascript.
Comparing this library to NaturalDocs the choice seems to me to come down to two things: syntax and presentation. NaturalDocs gives you a really nice layout and a lot of flexibility in how you write your documentation inline, while jsDoc uses the same syntax as javadoc.
Does it matter if we use the same syntax as javadoc? Do we care if the output looks pretty and has a nicer interface? Which one? Spend a few minutes reading the documentation on each of these packages and sound off here, as the work on the global framework has gotten to the point where documentation is going to start to be the next thing that needs focus.
I like the documentation artifacts produced by NaturalDocs, but the lack of IDE support is frustrating. I’ve been using ScriptDoc for all my own documentation because it has IDE support in the Eclipse IDE. This javadoc-like syntax is supported by both Aptana and JSEclipse.
I haven’t found any IDEs or editors that can display NaturalDoc notes during code completion, and once you have a taste of context sensitive documentation you’ll really miss it.
NaturalDocs is written in Perl. Technically it should be possible to use it to generate ScriptDoc, but my Perl foo is very weak and I gave up. I’m planning to make another attempt to do it by hand… I burned three hours last time and gave up in frustration. Maybe a regular expression based solution would do the job, but my regex foo is also weak.