There are two ways to do in-code documentation.
The first way is implicit. The tool parses the code, finding which things are functions and which things are classes, and then grabs comment blocks located near these structures. This method requires detailed knowledge about the programming language.
The second way is explicit. The tool requires the documentation author to notate what is what. This requires little information about the programing language since most languages share syntactic structures like functions, classes, variables, and so on. The generating tool needs to know only what comments look like.
Some tools support one of these methods, and some support both. Ideally they would all support explicit documentation, but also help you make the documentation more concise by figuring out what you are documenting automatically. Keep these distinctions in mind while reading about the tools below.
It seems weird that it does not support any language it knows the comment syntax for, since it allows many kinds of explicit documentation. Maybe the authors will fix this omission someday.
JSDoc. Next up was JSDoc, which also has Javadoc style syntax. Out of the box on Mac OS X, JSDoc segfaults. It seems to be related to recursion depth of the regular expressions, and installing a Perl from source worked around the issue. The problem with JSDoc is that it assumes a lot about how you write the code and allows no explicit documentation. It cannot detect constructors inside JSON style object definitions and doesn’t seem to deal well with prototypes. If you program in the style it supports, it probably works great, otherwise you are screwed. In addition to this, JSDoc produces the worst HTML output I’ve ever seen. I think it could give early versions of FrontPage some competition in this regard. Don’t take my word for it though; just look at their example. It has all the text content inside of <ul> tags!
Natural Docs For The Win
Natural Docs is not without its issues, but they are mostly minor. The indexes for grouped documentation don’t seem to be generated correctly, but I can forgive this since most of the other tools had no indexes at all. It also can’t document part of a class in one place and part in another unless you don’t mind the documentation also showing up in two locations. I think both of these problems could be easily fixed if they bothered you. I was able to work around the latter easily with very minor code tweaks.
You can see the Strophe preview documentation to get an idea of what the output look like. Here is what the input looks like for a typical function.
/** Constructor: Strophe.Connection
* Create and initialize a Strophe.Connection object.
* (String) service - The BOSH service URL.
* A new Strophe.Connection object.
I think the output and tool are nice enough to use that I will probably convert the C version of Strophe to Naturals Docs as well, instead of using Doxygen.
Hopefully this inspires some people to document their code better. I’m sure I’m not the only one that could improve in this area.