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

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

[Eric M. Ludlam]

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

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

[Stefan Monnier]

>   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.

And I agree with your approach.  The only problem I can see really
(besides those in the coding convention ;-), is that when a
test fails, the testing is aborted.  That is unfortunate when
I want to leave one argument unmentioned but would still want
to check that the symbols are properly quoted.

Also that means that C-u checkdoc-current-buffer RET does not
actually list all the issues.  Maybe there's a way to configure
it differently, but it I didn't see it.


	Stefan

Re[2]: checkdoc (was: mh-e 6.2 imminent)

[Eric M. Ludlam]

>>> "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> seems to think that:
>>   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.
>
>And I agree with your approach.  The only problem I can see really
>(besides those in the coding convention ;-), is that when a
>test fails, the testing is aborted.  That is unfortunate when
>I want to leave one argument unmentioned but would still want
>to check that the symbols are properly quoted.
>
>Also that means that C-u checkdoc-current-buffer RET does not
>actually list all the issues.  Maybe there's a way to configure
>it differently, but it I didn't see it.
  [ ... ]

Yes, the mechanism is not very flexible which is why I had originally
started trying to rearchitect the insides.  I guess I couldn't fathom
why anyone would not want to fix all the problems. ;)

The prefix argument should allow more than one error message per doc
string, with a few exceptions in some cascading style checks.
Perhaps it broke somewhere in its history.

Eric

-- 
          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

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

[Bill Wohler]

"Eric M. Ludlam" <eric@siege-engine.com> writes:

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

  Definitely. The manual and checkdoc should be kept in sync and not
  play different tunes.

--
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and mh-e. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.