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

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

Jeremy Bryant <[email-masked]> writes:

> Eli Zaretskii <[email-masked]> 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" <[email-masked]>
>>> 
>>> 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.

>From 3fefd7a9774a825af6497fa52ef22caf353e9044 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 | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/lisp/emacs-lisp/igc.el b/lisp/emacs-lisp/igc.el
index e9d897f9f64..85027a4c8d0 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,20 @@ igc--info-to-display
     (b igc--b)))
 
 (defun igc-display-diff ()
+  "Display the difference between IGC snapshots A-B.
+Used for debugging."
   (interactive)
   (setq igc--display-mode 'diff)
   (igc-stats))
 
 (defun igc-display-a ()
+  "Display IGC stats snapshot A from igc--roots."
   (interactive)
   (setq igc--display-mode 'a)
   (igc-stats))
 
 (defun igc-display-b ()
+  "Display IGC stats snapshot A from igc--roots."
   (interactive)
   (setq igc--display-mode 'b)
   (igc-stats))
@@ -174,21 +182,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 +222,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 +296,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 +305,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