Automated docstring testing

Automated docstring testing

[Oleh Krehel]

[-- Attachment #1: Type: text/plain, Size: 683 bytes --]


Hi all,

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

I think it's more convenient than M-x checkdoc, since compilation-mode
has a nicer interface.

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.

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

Let me know what you think of this idea, if it should be implemented,
and how it can be improved.

Oleh


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-batch-checkdoc-testing.patch --]
[-- Type: text/x-diff, Size: 1394 bytes --]

From bb5324675821876c2baf4d6b7ba18b6db614c4ea Mon Sep 17 00:00:00 2001
From: Oleh Krehel <ohwoeowho@gmail.com>
Date: Wed, 20 May 2015 16:03:06 +0200
Subject: [PATCH] Add batch checkdoc testing

* lisp/Makefile.in: New target "checkdoc".

* lisp/do-checkdoc.el: A sample file that checks the docstrings in "subr.el".
---
 lisp/Makefile.in    | 5 ++++-
 lisp/do-checkdoc.el | 4 ++++
 2 files changed, 8 insertions(+), 1 deletion(-)
 create mode 100644 lisp/do-checkdoc.el

diff --git a/lisp/Makefile.in b/lisp/Makefile.in
index 22d5ddc..522029d 100644
--- a/lisp/Makefile.in
+++ b/lisp/Makefile.in
@@ -471,7 +471,7 @@ distclean:
 maintainer-clean: distclean bootstrap-clean
 	rm -f TAGS
 
-.PHONY: check-declare
+.PHONY: check-declare checkdoc
 
 check-declare:
 	$(emacs) -l check-declare --eval '(check-declare-directory "$(lisp)")'
@@ -481,6 +481,9 @@ check-defun-dups:
 	        $$(find . -name '*.el' -print | grep -v 'loaddefs\.el') \
 	    | sort | uniq -d
 
+checkdoc:
+	$(emacs) -batch -l do-checkdoc.el
+
 # Dependencies
 
 ## None of the following matters for bootstrap, which is the only way
diff --git a/lisp/do-checkdoc.el b/lisp/do-checkdoc.el
new file mode 100644
index 0000000..8282e23
--- /dev/null
+++ b/lisp/do-checkdoc.el
@@ -0,0 +1,4 @@
+(require 'checkdoc)
+(dolist (file '("subr.el"))
+  (with-current-buffer (find-file file)
+    (checkdoc-current-buffer t)))
-- 
1.8.4

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