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

From: Jeremy Bryant <[email-masked]>
Date: Tue, 08 Apr 2025 22:12:51 +0100

Pip Cet <[email-masked]> writes:

> "Jeremy Bryant" <[email-masked]> 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.

>From 5f315d6b197e0e13ff2829837d13b49dc1afa11e Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <[email-masked]>
Date: Thu, 20 Mar 2025 22:19:33 +0000
Subject: [PATCH] ; * lisp/emacs-lisp/igc.el: checkdox fixes for interactive
 functions

Add docstring for interactive functions:
(igc-snapshot)
(igc-display-diff)
(igc-display-a)
(igc-display-b)
(igc--roots-a)
(igc--roots-b)
(igc-roots-display-diff)
(igc-roots-display-a)
(igc-roots-display-b)
(igc--roots-snapshot)
(igc-stop-collecting-stats)

Add docstring for variables:
(igc--a)
(igc--b)
(igc--display-mode)
(igc-stats-time-format)
---
 lisp/emacs-lisp/igc.el | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/lisp/emacs-lisp/igc.el b/lisp/emacs-lisp/igc.el
index e9d897f9f64..099e916c14c 100644
--- a/lisp/emacs-lisp/igc.el
+++ b/lisp/emacs-lisp/igc.el
@@ -36,11 +36,15 @@ igc--diff
 	   when (and n1 n2 (/= n1 n2))
 	   collect (list t1 (- n1 n2) (and s1 (- s1 s2)))))
 
-(defvar igc--a nil)
-(defvar igc--b nil)
-(defvar igc--display-mode 'a)
+(defvar igc--a nil
+  "IGC snapshot A.  Used for debugging.")
+(defvar igc--b nil
+  "IGC snapshot B.  Used for debugging.")
+(defvar igc--display-mode 'a
+  "IGC stats current snapshot, \='a or \='b.")
 
 (defun igc-snapshot ()
+  "Take snapshot A or B depending on igc--display-mode."
   (interactive)
   (if (eq igc--display-mode 'a)
       (setq igc--a (igc-info))
@@ -54,16 +58,19 @@ igc--info-to-display
     (b igc--b)))
 
 (defun igc-display-diff ()
+  "Display the difference between IGC snapshots A and B."
   (interactive)
   (setq igc--display-mode 'diff)
   (igc-stats))
 
 (defun igc-display-a ()
+  "Display IGC stats snapshot A.  See igc-stats-mode."
   (interactive)
   (setq igc--display-mode 'a)
   (igc-stats))
 
 (defun igc-display-b ()
+  "Display IGC stats snapshot B.  See igc-stats-mode."
   (interactive)
   (setq igc--display-mode 'b)
   (igc-stats))
@@ -174,21 +181,26 @@ igc--roots-diff
 	   unless (= n1 n2)
 	   collect (list t1 (- n1 n2) (and s1 (- s1 s2)))))
 
-(defvar igc--roots-a nil)
-(defvar igc--roots-b nil)
+(defvar igc--roots-a nil
+  "IGC roots snapshot A.  Used for debugging statistics.")
+(defvar igc--roots-b nil
+  "IGC roots snapshot B.  Used for debugging statistics.")
 (defvar igc--roots-display-mode 'a)
 
 (defun igc-roots-display-diff ()
+"Display the difference between IGC roots snapshots A and B."
   (interactive)
   (setq igc--roots-display-mode 'diff)
   (igc-roots-stats))
 
 (defun igc-roots-display-a ()
+  "Display IGC roots for snapshot A."
   (interactive)
   (setq igc--roots-display-mode 'a)
   (igc-roots-stats))
 
 (defun igc-roots-display-b ()
+  "Display IGC roots for snapshot B."
   (interactive)
   (setq igc--roots-display-mode 'b)
   (igc-roots-stats))
@@ -209,6 +221,7 @@ igc--roots-info
     (cl-loop for i being the hash-values of h collect i)))
 
 (defun igc--roots-snapshot ()
+  "Display roots snapshots a or b."
   (interactive)
   (if (eq igc--roots-display-mode 'a)
       (setq igc--roots-a (igc--roots-info))
@@ -282,6 +295,7 @@ igc--sqlite
 
 ;;;###autoload
 (defun igc-stop-collecting-stats ()
+  "Stop collecting IGC stats."
   (interactive)
   (when igc--collect-timer
     (cancel-timer igc--collect-timer)
@@ -290,7 +304,8 @@ igc-stop-collecting-stats
       (sqlite-close igc--sqlite)
       (setq igc--sqlite nil))))
 
-(defvar igc-stats-time-format "%T.%3N")
+(defvar igc-stats-time-format "%T.%3N"
+  "Time format when exporting IGC stats, e.g. to csv or sqlite.")
 
 (defun igc--collect-stats-csv ()
   (let ((buffer (get-file-buffer igc--collect-file)))
-- 
2.47.2