4 Small Steps Towards Awesome Clojure Docstrings
Through my work on cljdoc I spent a lot of time looking at documentation and implementing code to render documentation. This made me more aware of the various facilities in Clojure documentation generators (codox, cljdoc, ...) and I would like to use this post to share that awareness with the wider Clojure community.
1. Backtick-Quote Function Arguments & Special Keywords
Whenever referring to an argument or special keywords, quote them using Markdown style ‘backticks‘. This makes them stand out more when reading the docstring, making it easier to visually parse and skim. Emacs also nicely highlights this (possibly others too).
(defn conj!
[coll x]
"Adds `x` to the transient collection, and return `coll`. The 'addition'
may happen at different 'places' depending on the concrete type."
,,,)
2. Link To Other Functions Using [[Wikilink]] Syntax
Functions call each other and sometimes it can be useful to link to other functions. In Codox and cljdoc you can do this by wrapping the var name in wikilink-style double brackets:
(defn unlisten!
"Removes registered listener from connection. See also [[listen!]]."
[conn key]
(swap! (:listeners (meta conn)) dissoc key))
Featured here:
datascript.core/unlisten!. To link to vars in other namespaces, fully qualify the symbol
in the brackets, e.g. [[datascript.core/listen!]].
3. Include Small Examples
On cljdoc all docstrings are interpreted as Markdown. With Codox this can be achived with a small configuration tweak. This means you have access to all the text formatting facilities that Markdown provides including code blocks. Code blocks can be fantastic when trying to show how a function is used in a bigger context, as very nicely shown in the Keechma Toolbox documentation:
See the source of this majestic docstring.
4. Use Tables To Describe Complex Options Maps
cljdoc's Markdown implementation supports tables as well. Those
can be very useful when having a function that receives a map of
options, like
reitit.core/router:
See the source of this beautiful docstring.
Closing
These trivial to implement improvements can make your docstrings 1000x times nicer to read (scientific studies have shown). Also they will just look plain awesome on cljdoc. Check out some examplary docstring work done by Nikita Prokopov here:
And please tell me about other projects with exceptional documentation or even more ways to make docstrings awesome.