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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 37034 in the body.
You can then email your comments to 37034 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Damien Cassou <damien <at> cassou.me>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.2.90;
 checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun
Date: Thu, 15 Aug 2019 09:38:10 +0200

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

Message #8 received at 37034 <at> debbugs.gnu.org (full text, mbox):

From: Alex Branham <alex.branham <at> gmail.com>
To: Damien Cassou <damien <at> cassou.me>
Cc: 37034 <at> debbugs.gnu.org
Subject: Re: bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric,
 cl-defmethod and cl-defun
Date: Thu, 15 Aug 2019 09:54:47 -0500

[Message part 1 (text/plain, inline)]

tags 37034 + patch
quit

On Thu 15 Aug 2019 at 09:38, Damien Cassou <damien <at> 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

[0001-Make-checkdoc-check-cl-lib-function-docstrings.patch (text/x-diff, inline)]

From d52d04d62c14c0c228a5d430188db5c76cac767d Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham <at> 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

Message #13 received at 37034 <at> debbugs.gnu.org (full text, mbox):

From: Damien Cassou <damien <at> cassou.me>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: 37034 <at> debbugs.gnu.org
Subject: Re: bug#37034: 26.2.90;
 checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun
Date: Fri, 16 Aug 2019 14:28:30 +0200

Hi Alex,

Alex Branham <alex.branham <at> 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

Message #16 received at 37034 <at> debbugs.gnu.org (full text, mbox):

From: Alex Branham <alex.branham <at> gmail.com>
To: Damien Cassou <damien <at> cassou.me>
Cc: 37034 <at> debbugs.gnu.org
Subject: Re: bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric,
 cl-defmethod and cl-defun
Date: Fri, 16 Aug 2019 12:26:08 -0500

[Message part 1 (text/plain, inline)]

On Fri 16 Aug 2019 at 14:28, Damien Cassou <damien <at> 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

[0001-Make-checkdoc-check-cl-lib-function-docstrings.patch (text/x-patch, inline)]

From 9c0b32423dc95a2d66134132e21a0b59457cdb25 Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham <at> 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

Message #19 received at 37034 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: Damien Cassou <damien <at> cassou.me>, 37034 <at> debbugs.gnu.org
Subject: Re: bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric,
 cl-defmethod and cl-defun
Date: Fri, 16 Aug 2019 14:00:00 -0700

Alex Branham <alex.branham <at> 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

Message #26 received at 37034 <at> debbugs.gnu.org (full text, mbox):

From: Damien Cassou <damien <at> cassou.me>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Alex Branham <alex.branham <at> gmail.com>
Cc: 37034 <at> debbugs.gnu.org
Subject: Re: bug#37034: 26.2.90;
 checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun
Date: Sat, 17 Aug 2019 13:45:05 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> Alex Branham <alex.branham <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.