Why is this library special?
- Works anywhere, not only on Rhino. (n.b. by “anywhere” I mean “node.js”, but there’s only a handful of code that needs to be abstracted for it to work on Rhino and in the browser, too, and I plan on doing just that.)
- Highly extensible, with initially planned support for two code commenting styles (dojodoc and jsdoc).
Wait, highly extensible? Tell me more!
Your code might run in a variety of environments and exploit natively available functionality of each environment. If the documentation parser doesn’t know about all those delicious native objects, it can’t help you document anything you borrow from them. Pluggable environments let you define all the built-ins of the environment your code runs in so it doesn’t fall over when you try to
var slice = .slice;.
Chances are good that whatever library you’re using has at least one function that retrieves, decorates, or iterates over objects that you need to document. Adding custom call handlers makes it possible for the documentation parser to understand and evaluate these special calls so that the correct properties exist on the correct objects and that any special magic that these functions might represent can be annotated.
Some people don’t like the standard jsdoc syntax, and that’s cool. If you’ve extended jsdoc with some new tags, or use some completely different format like dojodocs, Natural Docs, or docco – or, after an evening of heavy drinking, created your own custom documentation format from scratch – writing a new documentation processor will enable you to process any format your heart desires. It will not, however, cure your cirrhosis.
Once the code has been parsed and the documentation parsed, you’ll need to output the result to a format that you (or some tool other than you) can actually use! Exporters are completely isolated from the documentation processing workflow, so you can pick and choose one (or lots of) exporters for your final output.
git clone --recursive https://github.com/csnover/js-doc-parse.git
config.jsas appropriate for your environment. For parsing Dojo Toolkit source, you should only need to set
environmentConfig.basePathto the path to your Dojo 1.8 checkout.
./parse.sh file-or-directory [file-or-directory…]to generate documentation for the files/directories you’ve specified. By default, this documentation will be exported to
details.xml; update the exporter configuration if you want it to go elsewhere.