Disambiguate behavior of def with doc-string

Question

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.

Answer 1

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?

Answer 2

_Comment made by: bronsa_

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

Answer 3

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)]

Answer 4

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)

Answer 5

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