doall docstring

Question

The docstring for doall states:

...other than those needed to produce the first element in the seq ...

I believe this stems from the time before chunked seqs, and perhaps "first elements" would be more correct ?

Answer 1

I'm either not understanding the doc string, or it needs to be substantially changed:

When lazy sequences are produced via functions that have side
effects, any effects other than those needed to produce the first
element in the seq do not occur until the seq is consumed. doall can
be used to force any effects. Walks through the successive nexts of
the seq, retains the head and returns it, thus causing the entire
seq to reside in memory at one time.

(ins)user=> (defn printed-range [n] (map print (range n)))
#'user/printed-range
(ins)user=> (let [x (printed-range 10)] nil)
nil
(ins)user=> (let [x (printed-range 10)] (first x))
0123456789nil

the doc seems to say that the first element will b realized, but only elements that are accessed are guaranteed to be realized

Comments

An adequate correction would simply change "do not" to "might not".

Most docstrings are more narrowly scoped.  doall is relatively extravagant with its fable.  A more thorough fix would be to remove the (over-simplified) general info, on the theory that this isn't the place.

P.S. The exact same observation applies to dorun.