* bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun @ 2019-08-15 7:38 Damien Cassou 2019-08-15 14:54 ` Alex Branham 0 siblings, 1 reply; 6+ messages in thread From: Damien Cassou @ 2019-08-15 7:38 UTC (permalink / raw) To: 37034 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun 2019-08-15 7:38 bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun Damien Cassou @ 2019-08-15 14:54 ` Alex Branham 2019-08-16 12:28 ` Damien Cassou 0 siblings, 1 reply; 6+ messages in thread From: Alex Branham @ 2019-08-15 14:54 UTC (permalink / raw) To: Damien Cassou; +Cc: 37034 [-- 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 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun 2019-08-15 14:54 ` Alex Branham @ 2019-08-16 12:28 ` Damien Cassou 2019-08-16 17:26 ` Alex Branham 0 siblings, 1 reply; 6+ messages in thread From: Damien Cassou @ 2019-08-16 12:28 UTC (permalink / raw) To: Alex Branham; +Cc: 37034 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun 2019-08-16 12:28 ` Damien Cassou @ 2019-08-16 17:26 ` Alex Branham 2019-08-16 21:00 ` Lars Ingebrigtsen 0 siblings, 1 reply; 6+ messages in thread From: Alex Branham @ 2019-08-16 17:26 UTC (permalink / raw) To: Damien Cassou; +Cc: 37034 [-- 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 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun 2019-08-16 17:26 ` Alex Branham @ 2019-08-16 21:00 ` Lars Ingebrigtsen 2019-08-17 11:45 ` Damien Cassou 0 siblings, 1 reply; 6+ messages in thread From: Lars Ingebrigtsen @ 2019-08-16 21:00 UTC (permalink / raw) To: Alex Branham; +Cc: Damien Cassou, 37034 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun 2019-08-16 21:00 ` Lars Ingebrigtsen @ 2019-08-17 11:45 ` Damien Cassou 0 siblings, 0 replies; 6+ messages in thread From: Damien Cassou @ 2019-08-17 11:45 UTC (permalink / raw) To: Lars Ingebrigtsen, Alex Branham; +Cc: 37034 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2019-08-17 11:45 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2019-08-15 7:38 bug#37034: 26.2.90; checkdoc doesn't support cl-defgeneric, cl-defmethod and cl-defun Damien Cassou 2019-08-15 14:54 ` Alex Branham 2019-08-16 12:28 ` Damien Cassou 2019-08-16 17:26 ` Alex Branham 2019-08-16 21:00 ` Lars Ingebrigtsen 2019-08-17 11:45 ` Damien Cassou
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).