RE: checkdoc (was: mh-e 6.2 imminent)

["Eric M. Ludlam" <eric@siege-engine.com>]

Hi,

  Every suggestion from the Emacs Lisp reference manual that could be
easily tested, and auto-fixed was put into checkdoc.  This has oft
provided contention over if the tests were good or bad.  I opted not
to post judgment and have no personal stake in the different tests.

  Every test in the checkdoc code is prefixed with a comment that
specifies why the test is there, thus a quote from the manual is
there, or I wrote in "Addendum" when I added something I thought was
lacking.

  I do recommend changing the manual if you want to hack out a test
though.

  Lastly, checkdoc's original organic growth lead to some lack of
configurability.  I have a reconstituted checkdoc engine, but never
finished porting the tests.  The engine would keep every test in it's
own function, and the test selection would be customizable via a
simple list.  Lute.Kamstra@cwi.nl offered to take that engine, and
finish porting the tests.  I don't know what the current state is.
It will be a long task though.

Eric

>> I've never heard of this `convention,' and indeed, it sounds kind of
>> dumb -- a `-flag' suffix doesn't really add any useful information
>> (if you know the _meaning_ of a variable, then you already know whether
>> it's boolean or not, and if you don't know the meaning, well, then it
>> hardly helps you to know that it's boolean!).
>
>It's sadly even mentioned in the elisp doc :-(
>
>	work/emacs-0% grep -C flag lispref/tips.texi 
>	@item
>	If a user option variable records a true-or-false condition, give it a
>	name that ends in @samp{-flag}.
>	[...]
>
>Luckily it's rarely folowed.
>
>> Why on earth does checkdoc try to enforce this?  Can we take that out?
>
>I'd be happy to.
>
>> [I have my own agendas of course -- I'd like to make checkdoc complain
>> if people use a `-p' suffix for variables, or a `-face' suffix for
>> faces...]
>
>Agreed for the `-p'.  For `-face', I'm still not sure either way.
>
>
>	Stefan
>

-- 
          Eric Ludlam:                 zappo@gnu.org, eric@siege-engine.com
   Home: http://www.ludlam.net            Siege: www.siege-engine.com
Emacs: http://cedet.sourceforge.net               GNU: www.gnu.org