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.

The purpose of this page is to summarize in one place some of the interactive visualizations I have worked on. Most of these were built...

"When you start on your journey to Ithaca, then pray that the road is long, full of adventure, full of knowledge... Always keep Ithaca fixed in your mind. To arrive there is your ultimate goal. But do not hurry the voyage at all." (from "Ithaca", by C. P. Cavafy)