Disambiguate behavior of def with doc-string

Description

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`.

Environment

REPL

Activity

Show:
jcr
July 6, 2018, 4:09 PM

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?

Nicola Mometto
July 7, 2018, 11:06 AM

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

jcr
July 8, 2018, 12:19 AM

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

Nicola Mometto
July 9, 2018, 1:48 PM

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)

Assignee

Unassigned

Reporter

import

Approval

Triaged

Patch

Code

Affects versions

Priority

Trivial
Configure