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

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

[Damien Cassou]

Hi,

I rely on checkdoc to write clean docstrings. I rely on CL when writing
libraries to facilitate writing extensions through
specialization. Nevertheless, checkdoc won't check the docstrings of
cl-defgeneric, cl-defmethod and cl-defun.

Best,

-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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

[Alex Branham]

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

tags 37034 + patch
quit

On Thu 15 Aug 2019 at 09:38, Damien Cassou <damien@cassou.me> wrote:

> I rely on checkdoc to write clean docstrings. I rely on CL when writing
> libraries to facilitate writing extensions through
> specialization. Nevertheless, checkdoc won't check the docstrings of
> cl-defgeneric, cl-defmethod and cl-defun.

Patch attached should fix the issue.

Thanks,
Alex


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 1617 bytes --]

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

bug#37034
---
 lisp/emacs-lisp/checkdoc.el | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 830743f5f8..ce36596423 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -933,7 +933,7 @@ 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)
        ,(pred symbolp)
        ;; Require an initializer, i.e. ignore single-argument `defvar'
        ;; forms, which never have a doc string.
@@ -1885,7 +1885,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)
-- 
2.22.0

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

[Damien Cassou]

Hi Alex,

Alex Branham <alex.branham@gmail.com> writes:
> tags 37034 + patch

thank you for your patch. Nevertheless, it's not going to be enough. For
example, CL methods can have this signature:

(cl-defmethod navigel-children ((entities list) callback)
  "Execute CALLBACK with the children of ENTITIES as argument."
  (navigel-async-mapcar entities  #'navigel-children callback))

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.

-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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

[Alex Branham]

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

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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Make-checkdoc-check-cl-lib-function-docstrings.patch --]
[-- Type: text/x-patch, Size: 2833 bytes --]

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

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

[Lars Ingebrigtsen]

Alex Branham <alex.branham@gmail.com> writes:

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

After doing some light testing, this seems to work for me too, and I'm
applying the patch.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Damien Cassou]

Lars Ingebrigtsen <larsi@gnus.org> writes:
> Alex Branham <alex.branham@gmail.com> writes:
>
>> * 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
>
> After doing some light testing, this seems to work for me too, and I'm
> applying the patch.


I think there are problems with this patch. I opened a new bug report:
bug#37063.

-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill