Menu

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

open
nobody
None
5
2008-02-27
2008-02-27
No

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=>

Discussion


Log in to post a comment.

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.