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:
- The D3 Visualization by Edward Lee (my only modification of the visualization itself was to include the opacity of the tick labels in the transitions)
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.
This is a topic which is close to my heart...
ReplyDeleteCheers! Where are your contact details though?
Manchester City Kläder HudsonGra Arsenal
Trøje Børn LoisHain
Essietfjl Neues Napoli Trikot BenjaminY