Re: Automated docstring testing

[Stefan Monnier]

> As I was just editing subr.el, I noticed that some functions there are
> missing a docstring, and a lot of them don't conform to `checkdoc'.
> I attach a patch that makes it possible to call:
>     make checkdoc

Looks like a good idea, but it's going to take some work to make it
usable: we'll need to tweak checkdoc to remove some of the things it
complains about (e.g. the preference for "-flag" for boolean vars, with
which I simply disagree) otherwise the output is just much too long and
will never get fixed.  IOW it should only include the things which we
really always want to fix.  Things like args not being mentioned in the
docstring aren't always actual bugs, so we shouldn't complain about them
(e.g. for interactive-only functions, the docstring often is written
from the interactive-user's point of view, so it should talk about the
region and the C-u prefix rather than about the function's own
arguments).  Or else we need to add some (lightweight/concise) way to
silence those complaints on a case-by-case basis.

These would be good changes regardless of this particular make target,
of course.

> I'm not yet sure if the file list should be passed to `make', or it
> should be hard-coded, so far I've just put '("subr.el") as the
> file list.

Good question.

> I also don't know where to put a file that the Makefile target wants to
> load, I've just put it in lisp/do-checkdoc.el.

If it's short, you can put the Elisp code inline in the Makefile.
Else you can put it in the `admin' subdirectory.  Putting it in `lisp'
is probably not a good idea, unless it can be used by unbundled
Elisp packages.  Another option is to put the code in checkdoc.el.


        Stefan