requesting change to doc string in (doc take-while)

Question

Requesting change to (doc take-while)

currently it says

---

clojure.core/take-while
([pred] [pred coll])
Returns a lazy sequence of successive items from coll while
(pred item) returns logical true. pred must be free of side-effects.
Returns a transducer when no collection is provided.

to

---

clojure.core/take-while
([pred] [pred coll])
Returns a lazy sequence of successive items from coll while
(pred item) returns logical true and stops at first false. pred must be free of side-effects.
Returns a transducer when no collection is provided.

This catches out people new to programing/clojure

see

https://stackoverflow.com/questions/69845947/why-is-take-while-returning-empty-sequence

Answer 1

Hi, thanks for the suggestion, but I don't think we will change this.

"while (pred item) returns logical true" is sufficient - "while" means "during the time when the condition holds" (and not when it doesn't). "I sing while I'm in the shower" does not need to also say "and stop singing when I get out of the shower".

Clojure core docstrings are intentionally very economical in their language. They are of course imperfect and nearly every release of Clojure has docstring updates, so we're open to changing them where that makes sense, but I don't think that's the case here.

Many beginners need additional information and we have great ancillary resources like https://clojuredocs.org/clojure.core/take-while where Clojure users can provide examples, additional commentary, links, etc to supplement the core docstring. The Clojure cheatsheet (https://clojure.org/api/cheatsheet) provides links into ClojureDocs as well.

Comments

The StackOverflow poster had missed the word "successive" (or had missed the API docs altogether).

---

Thanks for taking the time to reply.