Documentation

[jreinhardt]

We should have nice generated documentation.

I did a bit of web search and found the following things:

JSDoc seems to be popular to annotate APIs https://en.wikipedia.org/wiki/JSDoc

JSDoc3 is a tool to generate something from these annotations, looks promising http://usejsdoc.org/index.html

Headerdoc is a another tool that does that, looks ok https://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/HeaderDoc/intro/intro.html

Sphinx has a Javascript Domain http://sphinx-doc.org/domains.html#the-javascript-domain

Two Projects that try to do something like autodoc https://github.com/stdbrouw/jsdoc-for-sphinx https://github.com/Nuulogic/sphinx-jsapidoc

Naturaldocs looks nice conceptually, but has only limited support for Javascript http://www.naturaldocs.org/documenting.html

YUIDocs might also be ok http://yui.github.com/yuidoc/

Docco is for literate programming like documentation, not sure if that is what we want http://jashkenas.github.com/docco/

groc as well https://github.com/nevir/groc

PDoc is more traditional http://pdoc.org/

Opinions?

[jreinhardt]

List of Javascript Documentation Tools https://github.com/bebraw/jswiki/wiki/Documentation-Tools

Another API documentation alternative https://github.com/senchalabs/jsduck

Only JSON output https://github.com/visionmedia/dox

Doctor infers as much as possible from the source https://github.com/jdeal/doctor

Docco with JDoc Tags https://github.com/bebraw/jswiki/wiki/Documentation-Tools

Prose Documentation https://github.com/rfw/owldoc

[jreinhardt]

I tried NaturalDocs, but it is awkward, because it does not really know about the Javascript contexts. Otherwise it is nice.