The awful state of Javascript documentation tools
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
Written by Jimmy Yuen Ho Wong
Related protips
5 Responses
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 @tags in 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 they return 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!
@dpashkevich Hey thanks for the tip, I'll give it a go. It does look pretty good..
@wyuenho, in case you're interested, I created a grunt task that runs jsduck, for convenience.
https://github.com/dpashkevich/grunt-jsduck
@dpashkevich Ah thanks. I've already integrated JSDuck into Backgrid.js' build system with a simple one-liner in a Makefile. Thanks for the heads up though. Do you happen to know what repercussions the GPL ExtJS files JSDuck includes will have on my source code?
I guess no, unless you're re-distributing it.
You may want to check this thread http://stackoverflow.com/questions/94346/can-i-legally-incorporate-gpl-lgpl-open-sourced-software-in-a-proprietary-cl
