Michael Fogus just published a post about Marginalia, a new documentation system for Clojure based on Jeremy Ashkenas’ Docco for CoffeeScript. It’s work that Fogus started on late last year, and which Zachary Kim (the creator of ClojureDocs) picked up and improved on. The goal for Marginalia is to build a literate programming system, or something close to it, around Clojure.

My first exposure to the concept of literate programming was about ten years ago, when I was still doing a lot of work with Python. Edward K. Ream’s Leo was the tool that I used to experiment with LP, and to be honest, I didn’t get it. The idea of LP, as I thought I understood it then, was that you wanted your documentation and code to be intertwined, and readable: more like literature for humans, and less like a structured formula for computers. But the user interface for Leo required you to build up your system in a highly structured outline form. It was tedious. Writing code with Leo didn’t feel like any sort of programming I’d done before, and trying to write documentation with Leo sure didn’t feel like any sort of writing I’d done before. So after playing with it for awhile, and then getting frustrated with it, I moved on and haven’t thought any more literate programming until this morning.

Marginalia (in its current incarnation) takes a decidedly different, and for me more familiar tack, of embedding documentation comments directly in code. In that sense it’s no different from JavaDoc, or RDoc, or most other software documentation systems today. As you would hope, it picks up directly on the docstrings that you provide for namespaces, functions, etc.

It also parses out more general documentation text that you embed in comments that start with two semicolons.

Note that it supports Markdown-style formatting in both your docstrings as well as these special documentation comments. There’s also support for some fancier stuff, like displaying mathematical formulas written in LaTeX, that uses the MathJAX engine under the hood, but I haven’t gotten around to trying that yet.

I must admit that the primary attraction of Marginalia for me at the moment is that it produces pretty documentation. I’m a sucker for pretty documentation. But I am intrigued by Fogus’ claim that “The very process of using Marginalia will help to crystalize your understanding of [the] problem and its solution(s).” Near the end of his blog post, he proposes a set of guidelines (based on a similar set by Reg Braithwaite) for incorporating Marginalia into your Clojure software development process to achieve that goal.

Now, if you’re really into literate programming, Fogus’ blog post also refers (in a footnote) to Tim Daly’s work on “Clojure in Small Pieces”, a fork of the Clojure source code (re)written in LP style. This strikes me as a very ambitious effort, but one that I plan to keep tabs on as well. It will be interesting to see how studying this re-interpretation of the Clojure code influences one’s understanding of Clojure’s design and implementation.