Page Comparison

...

• Natural Docs
• JsDoc Toolkit (supersedes JSDoc)
• jGrouseDoc
• ScriptDoc
• Markdown

General Comments

• Markdown is a general text-to-HTML documentation generator, based on wiki-markup-like principles. It is not specific to API documentation at all. It might be something to consider for Tutorials, though.

• ScriptDoc is a standardized format for code comments, but as far as I can tell, there is no tool available for parsing those comments and generating HTML docs.

• The remaining three (Natural Docs, JsDoc Toolkit and jGrouseDoc) are designed for API docs, and generally work by parsing the comments in the code. The remainder of my comments will focus on these three systems.

Criteria

Responses to Colin's suggested criteria:

...

Other Comments

Full Language Support

• jGrouseDoc does read and use the function signature that is immediately following a comment header - but if the comment header is not present, the function signature is ignored.
• JsDoc Toolkit will parse functions in a namespace if the namespace has an @namespace tag defining it. This might produce docs organized by component, if judiciously used. Functions on a that object will not be properly parsed unless the that object is declared to be a namespace, which produces odd-looking navigation, and even then, might not work.

The implications for this are:

• If we want API docs for something, we must write the proper comments for it. If it's not properly commented, it won't be in the docs.

Comment Structure

• JsDoc Toolkit and jGrouseDoc are very javadoc-like. The format is almost identical, so developers familiar with javadoc comments will have no trouble commenting their code for one of these systems.

• Natural Docs uses a much more natural looking format, which is much easier for humans to read, but it is actually rather picky: Whitespace is very important, for example, and thus the comments will "take up a lot of space" in the file.

Output

• Natural Docs produces output that is file-based. That is, the main navigation lists the files, and the docs for each file lists the functions in that file, in order of their appearance in the file.
• JsDoc Toolkit produces output by class, and in each function description, mentions which file it is found in.
• jGrouseDoc produces output that is organized by files, as well as identifying global functions.

Quirks

• JsDoc Toolkit gives numerous warnings of the form "WARNING: Trying to document applySkin as a member of undocumented symbol that." I tried ensuring that the that object had a comment, but that didn't seem to address the issue. No documentation was produced for the function, nor anything else in that file.

Namespacing

• All of these things seem to consider everything we do to be in the global namespace.
• JsDoc Toolkit has a @namespace tag, but it is not terribly useful. Multiple occurrences in different files are all percieved to be in the same file, and don't affect the description of the functions in that file - they're

General Impressions

I tried generating the docs for our code using all three of these systems, starting with no modifications to the comments, then experimenting with adding comments to some functions.

...