Poner doc-strings en data vars, ¿se considera idiomático?

Question

Así que he definido algunos vars para contener datos de estado en mi código de clojure. Acabo de descubrir que puedo añadir un doc-cadena para aquellos VARs ej .:

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

que me permite llamar (doc *my-var*) en el REPL. Esto parece una tarea válida y útil, pero no parece una práctica común en el código (limitado) que he leído.

¿Esto es considerado clojure idiomático?

Answer 1

También se utiliza en los espacios de nombres de Clojure (como clojure.pprint):

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

Usted puede Wan't utilizar una macro conveniencia de clojure.contrib.def:

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

Answer 2

Desde clojure 1.3 , def ha permitido una docstring opcional.

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