Some Thoughts on Codex, a Common Lisp Documentation Tool

Codex is one of a small number of native documentation generators in lisp. It uses an unusual markdown format called Scriba. I have been using it to document img-genner since about 2 years ago.

In those two years there hasn’t been an update for it(Actually for at least 7), but that’s not terribly uncommon among common lisp development tools. You could claim that it’s because they stay good, but honestly that argument is kinda nebulous for the same reasons they’re nebulous for a c++ library from 2003(though, to be fairer, the language hasn’t changed at all unlike c++), mostly because who knows if the author is still 1. Alive, or 2. cares about the project. I take what I can to work with the tools I like 🙂

It’s an unusual markup language for my taste(Apparently it’s based on a markup called scribe which I’d never heard of before), and there’s little documentation for it, which is… frustrating to say the least, but at least it works alright.

Frankly the output is almost beautiful.

There are some choices I’m not sure about. For example, it requires you to request the inclusion of docstrings and sourcecode derived information explicitly for everything in your package. This is, to be honest, helping me find some issues in my code that I hadn’t looked at for years. But it’s also frustrating when you come from doxygen, which will by default show everything, even private members.

I suspect that it has that limitation because it is relying on information that needs to be retained in the memory of the interpreter, rather than having some gigantic set of parsers crawling the source code.

For a taste, here’s a listing for a section that places some documentation in img-genner.

    @begin(section)
      @title(Drawing)
      @cl:with-package[name="img-genner"](
      @cl:doc(function stroke-line)
      @cl:doc(generic fill-shape)
      @cl:doc(method fill-shape (shape ellipse) image stroker)
      @cl:doc(method fill-shape (shape rectangle) image stroker)
      @cl:doc(method fill-shape (shape polygon) image stroker))
    @end(section)

From there we can build the documentation as so, assuming we’re in the img-genner folder.

(ql:quickload :codex)
(codex:document :img-genner :manifest-path #P"docs/manifest.lisp")

Overall, I’m not terribly displeased with the output it makes here, and I’m looking forwards to getting back to other types of coding for tomorrow.