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

From: [email-masked] (GNU bug Tracking System)
Date: Tue, 15 Apr 2025 05:53:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
77142: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=77142
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#77142: [PATCH] ; * lisp/emacs-lisp/igc.el: checkdox fixes for interactive functions
From: Eli Zaretskii <[email-masked]>
To: Jeremy Bryant <[email-masked]>
Cc: [email-masked], [email-masked], [email-masked], [email-masked]
Date: Tue, 15 Apr 2025 08:52:15 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Jeremy Bryant <[email-masked]>
> Cc: [email-masked],  [email-masked],
>   [email-masked],  [email-masked]
> 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.

Subject: [PATCH] ; * lisp/emacs-lisp/igc.el: checkdox fixes for interactive functions
From: Jeremy Bryant <[email-masked]>
To: [email-masked], Pip Cet <[email-masked]>, GerdMöllmann<[email-masked]>, Helmut Eller <[email-masked]>
Date: Thu, 20 Mar 2025 22:27:00 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

Pip, Gerd, Helmut,

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

WDYT?

>From e803743e318260b82edc5838318ca5b80e33c45b 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..2d69585b729 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