Barely Code Related http://wongjim.posterous.com @wong_jim's take on software engineering posterous.com Thu, 22 Nov 2012 03:55:00 -0800 The awful state of Javascript documentation tools http://wongjim.posterous.com/the-awful-state-of-javascript-documentation-t http://wongjim.posterous.com/the-awful-state-of-javascript-documentation-t

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:

JSDoc-toolkit, JSDoc3

The JSDoc related tools are the heavy-weights when it comes to documenting API, and by that I mean really heavy in memory usage and very slow. They are forever tied to Rhino and support dozens of tags and aliases, mostly because many tags have to be used in groups to be meaningful, ex: @param, @type, @default etc. The syntax for documenting anything is way more verbose than the actual JS code. There is no way to document default values for option hashes. These tools seem to get utterly confused when multiple @default exists in a block. JSDoc3 also have a tendency to silently ignore a lot of questionable things, like if I have a @method tag on a function value assignment inside an object literal, but the object literal is not declared to be a part of anything using @lends. I also had a lot of trouble getting an indented block of example code snippet separated from anther description paragraph below. Is that even possible in JSDoc? JSDoc3 seems to be able to generate JSON data file tho, so that’s good.

YUIDoc

This one actually came close to satisfying all my requirements, but sadly there are a number of deal-breakers. First, it doesn’t understand @throw. Has the same problem as JSDoc with examples, but using Markdown solves it. The JSDoc-like tags are also incompatible with other JSDoc implementations like JSDoc3 and Closure compiler, most notably @class and @constructor. YUIDoc also generates a reasonable JSON data file by default, albeit in a completely different format from anything else.

Doctrine

This is also very promising tool that uses Esprima as the parser. It’s still quite alpha at the moment but it claims to support Google’s Closure JSDoc syntax. For reasons beyond my understanding Closure actually has the most elaborate and well defined syntax for documenting API signatures… except that it didn’t define what comes after = and complains loudly when something comes after it. So I can’t document default values, types are fine tho. I would like to see Doctrine further developed into a CLI tool with meaningful error messages.

Dox

Awful, or that I’m stupid because many people recommend it and I find it the least helpful. Judging from its source code and the JSON output, it seems it only understands 8 JSDoc tags. Oh right, it generates barely formatted Markdown. Meh.

Panino

Panino is a Cloud9 project and uses pdoc’s syntax for documenting signature, which is very very succinct and nice, but it also suffers from the problem of not being able to document default values easily. Having to prepend a * on every line is also not cool. It doesn’t install well in node because the executable doesn’t get installed into prefix/bin. Finally it insists on linkifying every type symbol which is also annoying. I mean, where do I point people to for Object? The Ecmascript PDF spec?

JFDoc

Another promising tool that uses Esprima to parse JS source code, but it’s also fairly incomplete and the master is very very broken. Too bad the maintainer is writing a Ph.D dissertation and doesn’t have time to maintain it at the moment.

Docco

I’m very sympathetic to the cause of Docco & friends after bumping into so much headache. Good JS documentation tools is hard to write and get right. Docco is simple and annotates source code well, too bad it doesn’t suit my purpose.

Am I missing anything out there that I should take a look?

Oh BTW, I have one request to all the node.js CLI tool authors out there, please catch your errors at the right places and give the end users some reasonable feedback so they can amend their input. Thanks.

Updated 2012-11-25

JSDuck

Since this post was published a few people have told me about the awesome capability JSDuck possesses so I decided to give it a try. At last, I’ve found The One True Way to write documentation for Javascript projects. It does everything I ask for. It is fast, generates useful warnings, has succinct syntax because it uses Esprima to parse the source code. It also support Closure’s type expression with it’s own addition. It has syntax support for option hashes, and it can format examples and Markdown fairly well (yay!), best of breed I must say. It also generates a bunch of JSONP metadata files. The generated HTML doc viewer is also very nicely done. Overall, I don’t have much to complain, except JSDuck is a Sencha/ExtJS project and comes with a GPLv3 license, which presents a lot of legal headaches as to what terms it places on your documentation and source code under what conditions. I’m still very puzzled at this point so just in case, I’ve re-licensed al the documents under GPLv3 and removed the JS source code the generated API docs link to.

Permalink | Leave a comment  »

]]>
http://posterous.com/images/profile/missing-user-75.png http://posterous.com/users/4wKaxiSpMpXz Jimmy Wong spiraller Jimmy Wong