bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun

[Alex Branham]

On Fri 16 Aug 2019 at 14:28, Damien Cassou <damien@cassou.me> wrote:

> But this crashes checkdoc+patch because it expects each element of the
> parameter list to be a symbol which (entities list) is not.
>
> Also, CL methods accept &key and &context to specify parameters. Those
> should be taken care of by checkdoc in one way or another.

True, thanks for reminding me. The attached patch should take care of
these two scenarios.

Alex

>From 9c0b32423dc95a2d66134132e21a0b59457cdb25 Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham@gmail.com>
Date: Thu, 15 Aug 2019 09:51:23 -0500
Subject: [PATCH] Make checkdoc check cl-lib function docstrings

* lisp/emacs-lisp/checkdoc.el (checkdoc--next-docstring)
(checkdoc-defun-info): Include cl-defun, cl-defgeneric,
cl-defmethod.
(checkdoc-this-string-valid-engine): Add cl-lib supported
keywords.
(checkdoc-defun-info): Ensure function parameters are a
"flat" list.  bug#37034
---
 lisp/emacs-lisp/checkdoc.el | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 830743f5f8..8c3276efb8 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -933,7 +933,8 @@ don't move point."
                            ;; Don't bug out if the file is empty (or a
                            ;; definition ends prematurely.
                            (end-of-file)))
-    (`(,(or 'defun 'defvar 'defcustom 'defmacro 'defconst 'defsubst 'defadvice)
+    (`(,(or 'defun 'defvar 'defcustom 'defmacro 'defconst 'defsubst 'defadvice
+            'cl-defun 'cl-defgeneric 'cl-defmethod 'cl-defmacro)
        ,(pred symbolp)
        ;; Require an initializer, i.e. ignore single-argument `defvar'
        ;; forms, which never have a doc string.
@@ -1680,7 +1681,10 @@ function,command,variable,option or symbol." ms1))))))
                   (last-pos 0)
                   (found 1)
                   (order (and (nth 3 fp) (car (nth 3 fp))))
-                  (nocheck (append '("&optional" "&rest") (nth 3 fp)))
+                  (nocheck (append '("&optional" "&rest" "&key" "&aux"
+                                      "&context" "&environment" "&whole"
+                                      "&body" "&allow-other-keys")
+                                    (nth 3 fp)))
                   (inopts nil))
               (while (and args found (> found last-pos))
                  (if (or (member (car args) nocheck)
@@ -1885,7 +1889,8 @@ the token checkdoc-order: <TOKEN> exists, and TOKEN is a 
symbol read
 from the comment."
   (save-excursion
     (beginning-of-defun)
-    (let ((defun (looking-at "(def\\(un\\|macro\\|subst\\|advice\\)"))
+    (let ((defun (looking-at
+                  
"(\\(?:cl-\\)?def\\(un\\|macro\\|subst\\|advice\\|generic\\|method\\)"))
          (is-advice (looking-at "(defadvice"))
          (lst nil)
          (ret nil)
@@ -1951,7 +1956,10 @@ from the comment."
        ;; This is because read will intern nil if it doesn't into the
        ;; new obarray.
        (if (not (listp lst)) (setq lst nil))
-       (if is-advice nil
+       (unless is-advice
+          ;; lst here can be something like ((foo bar) baz) from
+          ;; cl-lib methods; flatten it:
+          (setq lst (flatten-tree lst))
          (while lst
            (setq ret (cons (symbol-name (car lst)) ret)
                  lst (cdr lst)))))
-- 
2.22.0