Subject: Re: bug#46918: 28.0.50; checkdoc fooled by qualified method

From: Mauro Aranda <[email-masked]>
Date: Thu, 04 Mar 2021 10:31:32 -0300

tags 46918 patch
quit

I attach a patch to fix this, together with new tests.  I wanted to keep
the first case simple, so I moved the handling of cl-defmethod to a
different case.

>From 3d6e813a42f3472c817cc512ccba60c70e04b64e Mon Sep 17 00:00:00 2001
From: Mauro Aranda <[email-masked]>
Date: Thu, 4 Mar 2021 08:34:58 -0300
Subject: [PATCH] Make checkdoc work with qualified methods

* lisp/emacs-lisp/checkdoc.el (checkdoc--next-docstring): Handle
cl-defmethod in a case of its own.  Check for the presence of
qualifiers, and skip them accordingly until the docstring.

* test/lisp/emacs-lisp/checkdoc-tests.el (checkdoc-cl-defmethod-qualified-ok)
(checkdoc-cl-defmethod-with-extra-qualifier-ok)
(checkdoc-cl-defmethod-with-extra-and-nil-args-ok): Add tests for the fix.
---
 lisp/emacs-lisp/checkdoc.el            | 21 +++++++++++++++++++-
 test/lisp/emacs-lisp/checkdoc-tests.el | 27 ++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 75aefdc7ba..213ab43184 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -932,7 +932,7 @@ checkdoc--next-docstring
                            ;; definition ends prematurely.
                            (end-of-file)))
     (`(,(or 'defun 'defvar 'defcustom 'defmacro 'defconst 'defsubst 'defadvice
-            'cl-defun 'cl-defgeneric 'cl-defmethod 'cl-defmacro)
+            'cl-defun 'cl-defgeneric 'cl-defmacro)
        ,(pred symbolp)
        ;; Require an initializer, i.e. ignore single-argument `defvar'
        ;; forms, which never have a doc string.
@@ -942,6 +942,25 @@ checkdoc--next-docstring
      ;; initializer or argument list.
      (forward-sexp 3)
      (skip-chars-forward " \n\t")
+     t)
+    (`(,'cl-defmethod
+        ,(pred symbolp)
+        . ,rest)
+     (down-list)
+     (forward-sexp (pcase (car rest)
+                     ;; No qualifier, so skip like we would have skipped in
+                     ;; the first clause of the outer `pcase'.
+                     ((pred listp) 3)
+                     (':extra
+                      ;; Skip the :extra qualifier together with its string too.
+                      ;; Skip any additional qualifier.
+                      (if (memq (nth 2 rest) '(:around :before :after))
+                                  6
+                                5))
+                     ;; Skip :before, :after or :around qualifier too.
+                     ((or ':around ':before ':after)
+                      4)))
+     (skip-chars-forward " \n\t")
      t)))
 
 ;;;###autoload
diff --git a/test/lisp/emacs-lisp/checkdoc-tests.el b/test/lisp/emacs-lisp/checkdoc-tests.el
index 93015fbb10..7a7aa9fb3c 100644
--- a/test/lisp/emacs-lisp/checkdoc-tests.el
+++ b/test/lisp/emacs-lisp/checkdoc-tests.el
@@ -52,6 +52,33 @@ checkdoc-cl-defmethod-with-types-ok
     (insert "(cl-defmethod foo ((a (eql smthg)) (b list)) \"Return A+B.\")")
     (checkdoc-defun)))
 
+(ert-deftest checkdoc-cl-defmethod-qualified-ok ()
+  "Checkdoc should be happy with a `cl-defmethod' using qualifiers."
+  (with-temp-buffer
+    (emacs-lisp-mode)
+    (insert "(cl-defmethod test :around ((a (eql smthg))) \"Return A.\")")
+    (checkdoc-defun)))
+
+(ert-deftest checkdoc-cl-defmethod-with-extra-qualifier-ok ()
+  "Checkdoc should be happy with a :extra qualified `cl-defmethod'."
+  (with-temp-buffer
+    (emacs-lisp-mode)
+    (insert "(cl-defmethod foo :extra \"foo\" ((a (eql smthg))) \"Return A.\")")
+    (checkdoc-defun))
+
+  (with-temp-buffer
+    (emacs-lisp-mode)
+    (insert
+     "(cl-defmethod foo :extra \"foo\" :after ((a (eql smthg))) \"Return A.\")")
+    (checkdoc-defun)))
+
+(ert-deftest checkdoc-cl-defmethod-with-extra-qualifier-and-nil-args-ok ()
+  "Checkdoc should be happy with a 0-arity :extra qualified `cl-defmethod'."
+  (with-temp-buffer
+    (emacs-lisp-mode)
+    (insert "(cl-defmethod foo :extra \"foo\" () \"Return A.\")")
+    (checkdoc-defun)))
+
 (ert-deftest checkdoc-cl-defun-with-key-ok ()
   "Checkdoc should be happy with a cl-defun using &key."
   (with-temp-buffer
-- 
2.30.0