doc strings consistent naming (e.g., "doseq")

Stephen C. Gilardi — Wed, 27 Feb 2008 16:17:42 -0000

Doc strings should use names that are consistent with argument lists. As an example, here are the docs for "doseq" in SVN 702:

user=> (doc doseq)
-------------------------
clojure/doseq
([item list & body])
Macro
Repeatedly executes body (presumably for side-effects) with binding-form bound to successive items from coll.
Does not retain the head of the sequence. Returns nil.
nil
user=>

The arguments refer to "item" and "list", the docs refer to "binding-form" and "coll". These should be brought into line in this case and in any other cases where they're not in agreement.

One might also consider a convention (as in emacs) where words that represent literals are distinguished somehow (as in all-caps) so they can be represented in some special way (as in italics) when the doc string is presented by a pretty printer.

For example:

user=> (doc doseq)
-------------------------
clojure/doseq
([item coll & body])
Macro
Repeatedly executes BODY (presumably for side-effects) with ITEM bound to successive items from COLL.
Does not retain the head of COLL. Returns nil.
nil
user=>

Recent changes to 1: doc strings consistent naming (e.g., "doseq")

doc strings consistent naming (e.g., "doseq")