Re[2]: doc-strings in src/ and the first line

[Eric M. Ludlam]

>>> Richard Stallman <address@hidden> seems to think that:
>    As the original author,    I know that one problem is that it is tied
>    closely to being in an Emacs Lisp buffer.  Another problem deals with
>    the interactive nature.
>
>I seem to recall that the rules it checks are not exactly the right
>rules.  It would be useful for someone to take a look at that, to
>compare it with the Documentation Tips appendix and with normal
>practice.  Run checkdoc on some files in Emacs; are the problems it
>reports really wrong?

Every individual check in checkdoc for documentation strings is
prefixed with a quote from the documentation.  Whenever it deviates
from the documentation it is specified as such with the label
"Addendum: " which I derived from what I saw was practiced, and where
the documentation was unspecific.

Other checks, such as those where checkdoc uses lisp-mnt were not
necessarily in the documentation.  In addition, checks on comments
were derived from conversations on gnu.emacs.help and may deviate from
the documentation.

The checks on what should appear in a `message', or `error', or
'y-or-n-p' was derived from the documentation of those individual
functions.

The short of it is that I did my best to follow the documetnation.
There have been several debates over some of the checks available in
checkdoc, and on occasion conversations have led to desires to change
the documentation, though I lost track if any of those changes
actually occurred.

One way to check the checks is to just run checkdoc on lots of
existing code in log mode (where it produces a log of errors instead
of trying to auto-fix them for you) and see if you disagree with any
errors it produces.  I happen to like the checks that it has, and
find discussions on specifics of style to be educational.

Eric

-- 
          Eric Ludlam:                 address@hidden, address@hidden
   Home: www.ultranet.com/~zappo            Siege: www.siege-engine.com
Emacs: http://cedet.sourceforge.net               GNU: www.gnu.org