34

Over the last year or so I've seen various announcements on the Clojure discussion list and other places about tools for documenting Clojure code. These range from full-on literate programming systems like Marginalia, and the tool being used to create the book "Clojure in Small Pieces" (or even emacs org-mode), to more conventional Javadoc-style solutions like Autodoc, and Javadoc itself which reportedly can be used with Clojure. A google search turns up various others, perhaps a few that deserve more attention, and for sure some that are just personal utilities for generating docs. My question is what are the best documentation tools, and what are their comparative strengths and weaknesses based on your experiences using them? I have not used any documentation tools to date, and am interested in experimenting with one or more.

rplevy
  • 5,393
  • 3
  • 32
  • 31
  • 2
    Just as a point of note, Marginalia is not a full-on literate programming tool. It does in many ways facilitate a literate style, but it does not in any way understand how to deal with out-of-order code commentary like the system used on "Clojure in Small Pieces". org-babel-clojure, or Knuth's CWEB. It's just a nice tool to facilitate code reading. – fogus Mar 17 '11 at 11:54
  • 1
    It sounds like both Autodoc and Marginalia are doc-string driven, and both have good integration with Leiningen, but the main difference is that Marginalia generates richer output, whereas Autodoc is more basic. Thanks! – rplevy Mar 17 '11 at 13:42

4 Answers4

21

I really like Marginalia if you want to take something like a literate programming approach. Marginalia traverses your source code, and produces an html formatted version with comments set beside code in a very clear text. Comments can be markdown formatted, making for a very readable final document. When reviewing source code that I've written some time ago, I find Marginalia really helps. Here's an example made from the Marginalia source itself.

Note that this differs from the original literate programming workflow, where you would write a file and source code is generated from that. With Marginalia, you write a regular source code file, and it's the documentation that's pulled out of that. The output is similar to what one might expect from literate programming, but this way you can still expect syntax highlighting in an editor, without any special literate programming support.

It interoperates with Leiningen, and I believe cake, though I haven't tried that myself.

Rob Lachlan
  • 14,289
  • 5
  • 49
  • 99
12

Codox is a more recent documentation generator for Clojure.

cderoove
  • 141
  • 1
  • 3
  • I'll vouch for this as a good alternative. Marginalia is impressive for presenting the code alongside the docs but has a bit too much 'personality', which I find distracting. Codox supposedly also has support for parsing inline html and possibly markdown, but ironically, the documentation is too sparse for me to figure it out (and not even codox output!) – jk. Dec 10 '12 at 10:56
11

Autodoc is an easy place to start and is what Clojure core and Clojure contrib produce.

Easy to use with Maven. I'm not sure if plugins exist for Leiningen or Cake.

Alex Miller
  • 69,183
  • 25
  • 122
  • 167
  • 3
    Looking at the link provided for [Autodoc](http://tomfaulhaber.github.com/autodoc/), there's a section on the lein plugin for autodoc: [Building Autodoc with Leiningen](http://tomfaulhaber.github.com/autodoc/#building_with_leiningen) – Shane Daniel Mar 17 '11 at 05:36
  • My project doesn't use a `clojure.main` main class and autodoc bails out because of this: `Error: Could not find or load main class clojure.main`. I haven't been able to find a way of specifying my own main class in a Maven POM. – Enda Farrell Dec 27 '13 at 20:53
6

If you want to go fully literate you should give org-babel-clojure a look. org-bable is a literate programming extension to the emacs org-mode.

If you want to use nrepl the following should be added to your .emacs:

(defun org-babel-execute:clojure (body params)
  "Execute a block of Clojure code with Babel."
  (let ((result-plist (nrepl-send-string-sync (org-babel-expand-body:clojure body params) nrepl-buffer-ns))
        (result-type  (cdr (assoc :result-type params))))
    (org-babel-script-escape
     (cond ((eq result-type 'value)  (plist-get result-plist :value))
           ((eq result-type 'output) (plist-get result-plist :value))
            (t                        (message "Unknown :results type!"))))))
mac
  • 9,885
  • 4
  • 36
  • 51
  • Now that swank-clojure has been deprecated in favor of nrepl, is there an update or alternative to org-babel-clojure? I'm investigating noweb for LP, but it would be great to have a repl during writing / development. – Reb.Cabin Aug 19 '13 at 12:35
  • 2
    org-babel-clojure works great nrepl. I have edited my reply above to reflect my current usage. – mac Aug 19 '13 at 16:50