GNU bug report logs - #77142
[PATCH] ; * lisp/emacs-lisp/igc.el: checkdox fixes for interactive functions

Previous Next

Full log

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

From: Pip Cet <pipcet <at> protonmail.com>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: gerd.moellmann <at> gmail.com, Eli Zaretskii <eliz <at> gnu.org>,
 eller.helmut <at> gmail.com, 77142 <at> debbugs.gnu.org
Subject: Re: bug#77142: [PATCH] ;
 * lisp/emacs-lisp/igc.el: checkdox fixes for interactive functions
Date: Tue, 08 Apr 2025 18:42:47 +0000

"Jeremy Bryant" <jb <at> jeremybryant.net> writes:

> Jeremy Bryant <jb <at> jeremybryant.net> writes:
>
>> Eli Zaretskii <eliz <at> gnu.org> writes:
>>
>>>> Date: Thu, 20 Mar 2025 22:27:00 +0000
>>>> From:  Jeremy Bryant via "Bug reports for GNU Emacs,
>>>>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
>>>>
>>>> Here is a patch with some checkdoc fixes for igc.el, with proposed
>>>> docstrings for interactive functions and some variables.
>>>>
>>>> WDYT?
>>>
>>> It triggers the following warning from byte-compiler:
>>>
>>>     ELC      emacs-lisp/igc.elc
>>>
>>>   In toplevel form:
>>>   emacs-lisp/igc.el:43:9: Warning: defvar `igc--display-mode' docstring has wrong usage of unescaped single quotes (use \=' or different quoting such as `...')
>>
>> OK I will fix it and send a revised patch.
>
> Revised patch attached.

There are some differences between the docstrings for igc-stats and
igc-roots. I think the igc-roots version is fine, and the igc-stats
docstrings should be adjusted accordingly.

> @@ -54,16 +58,20 @@ igc--info-to-display
>      (b igc--b)))
>
>  (defun igc-display-diff ()
> +  "Display the difference between IGC snapshots A-B.
> +Used for debugging."

I prefer "A and B", because we already spell out that we're calculating
the difference. As in the docstring for igc-roots-display-diff, I'd also
omit the "Used for debugging."

>    (interactive)
>    (setq igc--display-mode 'diff)
>    (igc-stats))
>
>  (defun igc-display-a ()
> +  "Display IGC stats snapshot A from igc--roots."

I'm not sure about the "from igc--roots" part. ... "in igc-stats-mode"
would work, but we can also omit it entirely.

Pip

Previous Next

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