Annotating a D3 Visualization with Docco

I have been casually learning how Michael Bostock's  D3 javascript charting library works.  One of the things I have been using is a slick example by Edward Lee that compares various aspects of history's largest empires.

When trying to understand code, it is helpful to see the explanation of what the code is doing adjacent to  the code itself.  A nice tool for creating such documentation is Docco, by Jeremy Ashkenas (creator of CoffeeScript, backbone.js, etc.).  Using only the source file itself, Docco produces HTML that displays the comments alongside the code. Comments are passed through Markdown, and code is passed through Pygments syntax highlighting. Docco can be used for JavaScript, CoffeeScript, and numerous other languages.

Using Docco, I walked through the details of Edward Lee's example, adding various comments and notes in the JavaScript code.  With his permission, the finished products are at the following links:

While Docco seems well suited for creating documentation that can help folks understand particular code,  it is probably not the best way to document an api, where a more concise presentation may be preferable.  And while creating such annotated code is useful for learners (and the author!), keeping the comments faithful to the code itself could be a challenge for moving code, as is always the case for source code comments.

Popular Posts