Welcome! Please see the About page for a little more info on how this works.

0 votes
in Docs by

As far as I can tell, it's impossible to use def to create a var that's unbound but has :doc metadata (or to change the :doc metadata of an existing var without also binding / changing the bound value).

This change clarifies the possible usages of def; i.e., if you supply doc-string, you must also supply init.

5 Answers

0 votes
by

Comment made by: jcr

This page is among the first google results for "clojure def docstring". Since it's a trivial documentation improvement, can it be merged for the next release?

0 votes
by
_Comment made by: bronsa_

FYI you can just do `(def ^{:doc "my-doc-here} var)`, altho for this use case `declare` should be preferred.
0 votes
by

Comment made by: jcr

Nicola, right; strictly speaking, the "it's impossible to use def to create a var that's unbound but has :doc metadata" bit of the issue description is incorrect, but that actually doesn't affect the correctness and usefullness of the change proposed in the patch itself. Just for clarification, this :forms meta actually reflects how {{def}} is implemented (while the current one does not):

[(def symbol) (def symbol doc-string? init)]

0 votes
by

Comment made by: bronsa

Definitely! I wasn't contesting this ticket, just letting you know you can use the explicit metadata syntax, in case you weren't aware of it (as the description seemed to suggest)

0 votes
by
Reference: https://clojure.atlassian.net/browse/CLJ-2159 (reported by alex+import)
...