muhuk's blog

Nature, to Be Commanded, Must Be Obeyed

May 10, 2016

Using Codox Effectively

Codox is a documentation tool for Clojure. It is primarily for API documentation but recent versions allow arbitrary files to be included. This post is a small collection of tips, some of which you may already know. If you are not familiar with Codox, you should probably start with its README.

1. Enable Markdown Globally

Although documenation format can be configured per var, Markdown should just be enabled globally unless you are extending codox with your own pre-processor:

(defproject ...
  :codox {:defaults {:doc/format :markdown}}
  ...)

2. Use h4 for Subheadings

Because var names are displayed with h3‘s:

(defn foo
  "Summary.

  #### Subheading

  More info."
  ...)

4. Cross Reference All the Things

The reader wants to spend the least time finding relevant documentation:

"Document [[module.submodule/var]]"

Also please make sure all your literals are wrapped with `.

5. Hide Auto-Generated Record Constructors

They just crowd the page. Given MyRecord, ->MyRecord & map->MyRecord is assumed.

(alter-meta! #'->RecordName assoc :no-doc true)

If you have any questions, suggestions or corrections feel free to drop me a line.