29

How to add docstrings and/or comments to Clojure libaries/namespaces as a whole, i.e. not just to specific functions within the namespace?

I've noticed that the clojure source uses (comment ...) in some places to do this (example), is that recommended?

Erik Kaplun
  • 37,128
  • 15
  • 99
  • 111
mikera
  • 105,238
  • 25
  • 256
  • 415

2 Answers2

47

You can add a docstring to any namespace in the ns form.

(ns my.name.space
  "Very cool namespace doing this and that."
  (:require other.cool.stuff))
kotarak
  • 17,099
  • 2
  • 49
  • 39
  • 1
    Indeed. And if Codox refuses to make it appear in the html files, try a `lein clean`. – Gra Jan 31 '16 at 16:45
19

You can add it to the ns declaration:

(ns ^{:author "mikera"
      :doc "My awesome library"}
  foo.bar.core)

The example you link to does that too - so not sure if this is what you mean? But I think it's the most "standard" - it will get picked up by documentation systems such as Codox and Autodoc.

Gert
  • 3,839
  • 19
  • 22
  • 2
    Note that `ns` is [defined](http://clojure.github.io/clojure/clojure.core-api.html#clojure.core/ns) to take a docstring as an optional second argument. This answer is equivalent to [kotarak's answer](http://stackoverflow.com/a/11611325/122762). – John Wiseman Feb 24 '14 at 23:43