Re: Changes in revision 114466

[Stephen Berman <stephen.berman@gmx.net>]

On Sun, 29 Sep 2013 22:21:18 -0700 (PDT) Drew Adams <drew.adams@oracle.com> wrote:

>> But I see one problem: not every {functions, variables, ...} needs
>> documenting.  E.g., some functions/variables use two hyphens to separate
>> prefix.  These functions/variables usually don't needs documenting.
>
> Why not?  Do you think developers do not need documentation?

According to Stefan Monnier (see
http://lists.gnu.org/archive/html/emacs-devel/2013-06/msg01129.html):

   [These functions/variables are] not meant to be used by other
   packages [, which] means that something defined with "--" can
   completely change (or disappear) from one release to the other.

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.  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 (at least the
documentation in the manual; such functions/variables could have doc
strings).

Steve Berman