RE: Changes in revision 114466

[Drew Adams <drew.adams@oracle.com>]

> This suggests that developers who use them should be working on the
> package they are in, hence reading and using the code and commentary of
> that package.

Yes, so?  Having code does not preclude having comments.  Having comments
does not preclude having documentation.

> In contrast, documentation for developers is, I think,
> aimed at explaining the code's public interface to use in developing
> other packages, not its private, internal only interface

Not in Emacs source code, IMHO - it should not be limited to that.
Not in dynamic, accessible code that users and developers of all sorts
are invited to customize, develop, extend, or do whatever they want with.

But anyone can make code as unclear as you like, and likewise to skip
commenting or skip documenting code...

From my point of view: add a doc string at the outset. You can then
take extra time later to ponder carefully whether it might be OK to
remove the doc string, if you really want to do that.

As opposed to lazily skipping doc strings to begin with and - maybe -
thinking later whether it might not be helpful to add a doc string.

Think first of others who might use the code, and that includes
"internal" maintainers.  It can even include yourself at a later date.

> (at least the documentation in the manual; such functions/variables
> could have doc strings).

We agree.  Most functions, variables, widgets, faces,... are *not*
documented explicitly in the manuals.  And that's as it should be.

My (likely lone) opinion remains that there is rarely a good reason
to skip adding a doc string.  And when there is, pondering whether to
do that should come afterward - careful reflection, as opposed to
immediately skipping it, as a knee-jerk reaction, just because
something has `--' in its name or whatever.

It is a false economy to skip adding a doc string.  Among other things,
trying to describe succinctly what something is or does can sometimes
lead one to see that it is in fact not well designed/defined, and
could benefit from, e.g, split up, etc.  If you cannot describe it
simply, that can be a sign that there is room for improvement in the
code/design.

Just one opinion.