Putting doc-strings on data vars, is it considered idiomatic?

Question

So I have defined some vars to hold state data in my clojure code. I have just discovered I can add a doc-string to those vars e.g.:

(def ^{:doc "Documentation for *my-var*"}
        *my-var*)

That lets me call (doc *my-var*) at the REPL. This seems like a valid and useful thing to do but it doesn't seem like common practice in the (limited) code I have read.

Is this considered idiomatic clojure?

Answer 1

Also used in Clojure namespaces (like clojure.pprint):

(def
 ^{:doc "The base to use for printing integers and rationals."
   :added "1.2"}
 *print-base* 10)

You may wan't to use a convenience macro from clojure.contrib.def:

(defvar *my-var*
  nil
  "Documentation for *my-var*")