RE: Changes in revision 114466

[Stephen J. Turnbull]

Drew Adams writes:

 > My (likely lone) opinion remains that there is rarely a good reason
 > to skip adding a doc string.

In this wide world you're not alone.  XEmacs policy has historically
been to put docstrings in everything that's "def'd" except for one-
line defsubsts and the like.  We also systematically convert leading
comments (and often comments where a docstring would go) to docstrings
more or less systematically.

On the other hand, many people (and the Emacs project, I believe) have
a policy of "docstrings document the API, if you want to know what
it's for or how it works, read the manual".  With good naming of
functions and parameters, often there is no need for a separate
description of the API.  Then the argument is that if you're going to
critically read the code anyway, the docstring means less lines of
code on screen.

I think you lose here on the basis that this is, pretty much, Emacs
policy.