Recently, I've been looking all over the net looking for the One True
Way to document Javascript programs and I must say I'm a little
disappointed. Long story short, I have the following requirements for
documenting Backgrid.js:
- Automatic API summary based on function signature
- Able to understand and document common JS idioms such as
throw, extending a prototype with an object literal, triggering events … etc. - Embed code examples in Markdown
- Gives reasonable error messages
- Saves parsed documentation info in some metadata JSON file
You would think that lots of tools do that (cause they claim they
can), but here's the reality:
Read more at my Posterous Blog
Not sure about your last point but have you tried jsduck?
It's a pretty good tool and has an awesome webapp for viewing the docs (imho the golden standard for all docs). Just take a look and get an idea of what things it supports.
Descriptions are written in Markdown (and there is even a special syntax for embedding images and videos), to embed code example just indent it with whitespace (syntax will be highlighted). There are tons of different tags including tags to describe events. You can add your own custom tags.
It's optimized for ExtJS/SenchaTouch but can be used as a standalone tool, you'll just need to put some more
@tagsin your doc comments. However the tool tries to infer as many information from the code as possible (it uses esprima parser under the hood). For example, it would mark your methods as "chainable" if theyreturn this.I haven't tried to use it outside of ExtJS but I like the conventions that jsduck sets, perhaps it will gain wider adoption in the future. Good luck!