CODEWITHSUNDEEP
documentationclojure
Alex Stoddard
Alex Stoddard

Reputation: 8344

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

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?

Upvotes: 17

Views: 1910

Answers (2)

deadghost
deadghost

Reputation: 5217

Since clojure 1.3, def has allowed an optional docstring.

(def *my-var*
  "My var does cool things (it really doesn't)."
  nil)

Upvotes: 19

Jürgen Hötzel
Jürgen Hötzel

Reputation: 19727

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

Upvotes: 10

Related Questions