GNU bug report logs - #37063
26.2.90; Problems with recent CL support in checkdoc

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 37063 in the body.
You can then email your comments to 37063 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
Cc: Alex Branham <alex.branham <at> gmail.com>, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: 26.2.90; Problems with recent CL support in checkdoc
Date: Sat, 17 Aug 2019 13:41:57 +0200

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

In the context of bug#37034, some initial support for CL functions and
methods was added to checkdoc.  On my code, the changes make checkdoc
trigger warnings on perfectly valid code IMO. For example,

  (cl-defmethod foo ((a list)) "Return A.")

Checkdoc complains that LIST should be described. I disagree with that,
list is a type, not a argument name.

I attach to this bug report a patch introducing test cases to
checkdoc-tests.el. If it's not possible to implement full support for CL
I prefer that checkdoc doesn't complain even if there is a bug in the
docstring rather than checkdoc complains when the docstring is correct.

Best,

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

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

[0001-checkdoc-CL-tests.patch (text/x-patch, attachment)]

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

From: dick.r.chiang <at> gmail.com
To: 37063 <at> debbugs.gnu.org
Subject: Re: bug#37063: 26.2.90; Problems with recent CL support in checkdoc
Date: Mon, 30 Sep 2019 12:52:36 -0400

[0001-checkdoc-identifying-formal-args.patch (text/x-diff, inline)]

From c97b08a1d6df46f674a18ab83ae86dc6a5ad3aa0 Mon Sep 17 00:00:00 2001
From: dickmao <none>
Date: Mon, 30 Sep 2019 10:04:49 -0400
Subject: [PATCH] ; checkdoc identifying formal args

* lisp/emacs-lisp/checkdoc.el (checkdoc-defun-info):
* test/lisp/emacs-lisp/checkdoc-tests.el: (Bug#37063)
---
 lisp/emacs-lisp/checkdoc.el            |  5 ++---
 test/lisp/emacs-lisp/checkdoc-tests.el | 16 ++++++++++++++++
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 51fb75da69..6c40bdf632 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -1952,11 +1952,10 @@ checkdoc-defun-info
 	;; new obarray.
 	(if (not (listp lst)) (setq lst nil))
 	(unless is-advice
-          ;; lst here can be something like ((foo bar) baz) from
+          ;; (car lst) 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)
+	    (setq ret (cons (symbol-name (car (flatten-tree (car lst)))) ret)
 		  lst (cdr lst)))))
       (nreverse ret))))
 
diff --git a/test/lisp/emacs-lisp/checkdoc-tests.el b/test/lisp/emacs-lisp/checkdoc-tests.el
index 1cefc4c366..b3cc943ac0 100644
--- a/test/lisp/emacs-lisp/checkdoc-tests.el
+++ b/test/lisp/emacs-lisp/checkdoc-tests.el
@@ -50,4 +50,20 @@ checkdoc-tests--next-docstring
     (should (looking-at-p "\"baz\")"))
     (should-not (checkdoc-next-docstring))))
 
+(ert-deftest checkdoc-tests--cl-defun ()
+  "Identify formal arguments from arbitary lisp code."
+  (with-temp-buffer
+    (let ((checkdoc-autofix-flag 'never))
+      (emacs-lisp-mode)
+      (insert "(cl-defun foo(&key bar &aux (baz (baz bar))) \"BAR BAZ.\")")
+      (should-not (checkdoc-defun)))))
+
+(ert-deftest checkdoc-tests--cl-defmethod ()
+  "Identify formal arguments from object types."
+  (with-temp-buffer
+    (let ((checkdoc-autofix-flag 'never))
+      (emacs-lisp-mode)
+      (insert "(cl-defmethod foo((a list)) \"Return A.\")")
+      (should-not (checkdoc-defun)))))
+
 ;;; checkdoc-tests.el ends here
-- 
2.23.0

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: dick.r.chiang <at> gmail.com
Cc: 37063 <at> debbugs.gnu.org
Subject: Re: bug#37063: 26.2.90; Problems with recent CL support in checkdoc
Date: Thu, 10 Oct 2019 02:21:55 +0200

dick.r.chiang <at> gmail.com writes:

> diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
> index 51fb75da69..6c40bdf632 100644
> --- a/lisp/emacs-lisp/checkdoc.el
> +++ b/lisp/emacs-lisp/checkdoc.el
> @@ -1952,11 +1952,10 @@ checkdoc-defun-info
>  	;; new obarray.
>  	(if (not (listp lst)) (setq lst nil))
>  	(unless is-advice
> -          ;; lst here can be something like ((foo bar) baz) from
> +          ;; (car lst) 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)
> +	    (setq ret (cons (symbol-name (car (flatten-tree (car lst)))) ret)
>  		  lst (cdr lst)))))
>        (nreverse ret))))

Thank you; I've now applied your patch here since it seems to fix the
use cases reported.  However, I didn't include the tests in your patch,
since they seemed to cover the same cases as Damien's (and they were
more extensive, so I applied those instead).

Besides, it doesn't look like you have copyright assignment papers on
file, and for larger patches we require copyright assignments to the
FSF.  If you plan on submitting further patches in the future, it might
be a good idea to do the paperwork now -- would you be willing to do so?

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: Alex Branham <alex.branham <at> gmail.com>, 37063 <at> debbugs.gnu.org
Subject: Re: bug#37063: 26.2.90; Problems with recent CL support in checkdoc
Date: Thu, 10 Oct 2019 02:22:52 +0200

Damien Cassou <damien <at> cassou.me> writes:

> In the context of bug#37034, some initial support for CL functions and
> methods was added to checkdoc.  On my code, the changes make checkdoc
> trigger warnings on perfectly valid code IMO. For example,
>
>   (cl-defmethod foo ((a list)) "Return A.")
>
> Checkdoc complains that LIST should be described. I disagree with that,
> list is a type, not a argument name.
>
> I attach to this bug report a patch introducing test cases to
> checkdoc-tests.el. If it's not possible to implement full support for CL
> I prefer that checkdoc doesn't complain even if there is a bug in the
> docstring rather than checkdoc complains when the docstring is correct.

After a patch was submitted that fixed most of the cases (except the
&context and &aux ones, I believe), I've applied your checkdoc-tests.el
patch (except those two functions).

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

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

From: Damien Cassou <damien <at> cassou.me>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Alex Branham <alex.branham <at> gmail.com>, 37063 <at> debbugs.gnu.org
Subject: Re: bug#37063: 26.2.90; Problems with recent CL support in checkdoc
Date: Thu, 10 Oct 2019 06:15:04 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> After a patch was submitted that fixed most of the cases (except the
> &context and &aux ones, I believe), I've applied your checkdoc-tests.el
> patch (except those two functions).

thank you!

-- 
Damien Cassou

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

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

From: Glenn Morris <rgm <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 37063 <at> debbugs.gnu.org,
 Alex Branham <alex.branham <at> gmail.com>
Subject: Re: bug#37063: 26.2.90; Problems with recent CL support in checkdoc
Date: Thu, 10 Oct 2019 12:45:59 -0400

Test failures:

https://hydra.nixos.org/build/102805902

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: Damien Cassou <damien <at> cassou.me>, Alex Branham <alex.branham <at> gmail.com>,
 37063 <at> debbugs.gnu.org
Subject: Re: bug#37063: 26.2.90; Problems with recent CL support in checkdoc
Date: Fri, 11 Oct 2019 07:48:15 +0200

Glenn Morris <rgm <at> gnu.org> writes:

> Test failures:
>
> https://hydra.nixos.org/build/102805902

Should be fixed now.

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

Previous Next

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