Clojure docstring for libraries/namespaces

Question

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?

Answer 1

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.

Answer 2

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))