Menu
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?
498
As mentioned above, Python docstrings are strings used right after the definition of a function, method, class, or module (like in Example 1). They are used to document our code. We can access these docstrings using the __doc__ attribute.
A Python docstring is a string used to document a Python module, class, function or method, so programmers can understand what it does without having to read the details of the implementation. Also, it is a common practice to generate online (html) documentation automatically from docstrings.
A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Docstrings are for people who are going to be using your code without needing or wanting to know how it works. Docstrings can be turned into actual documentation.
A docstring is just a regular python triple- quoted string that is the first thing in a function body or a module or a class. When executing a functionbody the docstring does not do anything like comments but Python stores it as part of the function documen-tation.
Since clojure 1.3, def has allowed an optional docstring.
(def *my-var*
"My var does cool things (it really doesn't)."
nil)
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*")
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
