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

0 votes
in Docs by

Promises can be invoked to deliver a value to them (same result as calling {{deliver}}), but this is not mentioned in the docstring:

(def p (promise)) (p 42) ;; same as (deliver p 42) @p ;; 42

Docstring before:

Returns a promise object that can be read with deref/@, and set, once only, with deliver. Calls to deref/@ ...

Proposed: Change docstring to:

clojure.core/promise ([]) Returns a promise object that can be read with deref/@, and set, once only, with deliver or by invoking the promise. Calls to deref/@ ...

Patch: clj-2480-2.patch
Prescreened by: Alex Miller

3 Answers

0 votes
by

Comment made by: hlewisship

I think we disagree about the value (or definition) of excessive concision in docstrings.

0 votes
by

Comment made by: pbwolf

Calling a promise does not always return the promise. Also, the docstring on deliver does not describe the return value. I hope the two docstrings (promise and deliver) will be kept in synch.

Opinion: it looks to me in the clojure source code like the IFn might just have been a reify hack to let deliver touch the promise. If calling the promise directly had been the plan for the official API, deliver would not exist. Do we really need two ways to deliver? If folks start eschewing deliver, I'll lose a great word to grep clj files for!

0 votes
by
Reference: https://clojure.atlassian.net/browse/CLJ-2480 (reported by hlewisship)
...