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

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 77142 in the body.
You can then email your comments to 77142 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: Jeremy Bryant <jb <at> jeremybryant.net>
To: bug-gnu-emacs <at> gnu.org, Pip Cet <pipcet <at> protonmail.com>, Gerd
 Möllmann
 <gerd.moellmann <at> gmail.com>, Helmut Eller <eller.helmut <at> gmail.com>
Subject: [PATCH] ; * lisp/emacs-lisp/igc.el: checkdox fixes for interactive
 functions
Date: Thu, 20 Mar 2025 22:27:00 +0000

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

Pip, Gerd, Helmut,

Here is a patch with some checkdoc fixes for igc.el, with proposed
docstrings for interactive functions and some variables.

WDYT?

[0001-lisp-emacs-lisp-igc.el-checkdox-fixes-for-interactiv.patch (text/x-diff, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: gerd.moellmann <at> gmail.com, pipcet <at> protonmail.com, 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: Sat, 22 Mar 2025 13:40:58 +0200

> 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 `...')

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

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: gerd.moellmann <at> gmail.com, pipcet <at> protonmail.com, 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: Sat, 22 Mar 2025 14:55:02 +0000

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.

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

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: gerd.moellmann <at> gmail.com, pipcet <at> protonmail.com, 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 19:30:22 +0100

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

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.

[0001-lisp-emacs-lisp-igc.el-checkdox-fixes-for-interactiv.patch (text/x-diff, attachment)]

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

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

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Pip Cet <pipcet <at> protonmail.com>
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 22:12:51 +0100

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

Pip Cet <pipcet <at> protonmail.com> writes:

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

New partially revised patch attached with comments below.

> 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.

What do you mean?  Is it igc-roots-stats?  If so, what changes?

>>  (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."

OK, done.

>
>>    (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.

OK, revision attached.

[0001-lisp-emacs-lisp-igc.el-checkdox-fixes-for-interactiv.patch (text/x-diff, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: gerd.moellmann <at> gmail.com, pipcet <at> protonmail.com, 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: Wed, 09 Apr 2025 14:48:31 +0300

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Cc: 77142 <at> debbugs.gnu.org,  pipcet <at> protonmail.com,
>   gerd.moellmann <at> gmail.com,  eller.helmut <at> gmail.com
> Date: Tue, 08 Apr 2025 19:30:22 +0100
> 
>  (defun igc-display-b ()
> +  "Display IGC stats snapshot A from igc--roots."
                                ^^^
Copy/pasta.

> +(defvar igc-stats-time-format "%T.%3N"
> +  "Time format when exporting IGC stats, e.g. to csv or sqlite.")

I think "Time format for exporting..." is better.

Thanks.

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

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: gerd.moellmann <at> gmail.com, pipcet <at> protonmail.com, 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: Mon, 14 Apr 2025 18:47:32 +0100

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

Attached revised patch to address below points.

[0001-lisp-emacs-lisp-igc.el-checkdox-fixes-for-interactiv.patch (text/x-diff, attachment)]

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

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Jeremy Bryant <jb <at> jeremybryant.net>
>> Cc: 77142 <at> debbugs.gnu.org,  pipcet <at> protonmail.com,
>>   gerd.moellmann <at> gmail.com,  eller.helmut <at> gmail.com
>> Date: Tue, 08 Apr 2025 19:30:22 +0100
>> 
>>  (defun igc-display-b ()
>> +  "Display IGC stats snapshot A from igc--roots."
>                                 ^^^
> Copy/pasta.

Indeed, sorry.  Trivial mistake corrected.
>
>> +(defvar igc-stats-time-format "%T.%3N"
>> +  "Time format when exporting IGC stats, e.g. to csv or sqlite.")
>
> I think "Time format for exporting..." is better.

OK - Style noted.

>
> Thanks.

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

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

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Cc: 77142 <at> debbugs.gnu.org,  pipcet <at> protonmail.com,
>   gerd.moellmann <at> gmail.com,  eller.helmut <at> gmail.com
> Date: Mon, 14 Apr 2025 18:47:32 +0100
> 
> Attached revised patch to address below points.

Thanks, installed on the igc branch, and closing the bug.

Previous Next

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