Choose a documentation extractor

[erikrose]

I'd like to be able to keep API docs in one place—in the source code—but still pull them out into HTML docs that slap more prose and context around them. I would like to avoid the common antipattern where the docs consist of an alphabetical list of routines, leaving the poor newcomer to wander linearly through them, trying to piece together an overview. Add contenders below.

Sphinxy things

Sphinx integration is nice because Sphinx is amazing, offering freeform docs in restructured text, indexing and glossary building, a good markup language with arbitrary nesting of constructs parsed in an unambiguous way, output of numerous formats, a decade plus of maturity, and the fact that I know it like the back of my hand.

• https://github.com/HumanBrainProject/jsdoc-sphinx. Use JSDoc in the code.
• https://github.com/Nuulogic/sphinx-jsapidoc. Use Sphinx-style docs in the code.

Pure JSDoc

The nice thing about this is that some JS tooling can consume it, like editors and Google's Closure Compiler (which uses type annotations to hint to the optimizer).

[erikrose]

I wrote something: https://github.com/erikrose/sphinx-js. It gives us everything we want, doesn't require Ruby or Java, and lets us use JSDoc notation within the JS code, which is probably considered normal for that language. The results: http://mozilla.github.io/fathom/.