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

[Pip Cet]

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

> Jeremy Bryant <jb@jeremybryant.net> writes:
>
>> Eli Zaretskii <eliz@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@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