GNU logs - #77142, boring messages

Message sent to bug-gnu-emacs@HIDDEN:

Subject: bug#77142: [PATCH] ; * lisp/emacs-lisp/igc.el: checkdox fixes for interactive functions
Resent-From: Jeremy Bryant <jb@HIDDEN>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@HIDDEN
Resent-Date: Thu, 20 Mar 2025 22:28:02 +0000
Resent-Message-ID: <handler.77142.B.174250966015420 <at> debbugs.gnu.org>
Resent-Sender: help-debbugs@HIDDEN
To: 77142 <at> debbugs.gnu.org, pipcet@HIDDEN, gerd.moellmann@HIDDEN, eller.helmut@HIDDEN
From: Jeremy Bryant <jb@HIDDEN>
Date: Thu, 20 Mar 2025 22:27:00 +0000
Message-ID: <87bjtvwd6z.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="=-=-="
Received-SPF: pass client-ip=2001:41d0:1004:224b::b9;
 envelope-from=jb@HIDDEN; helo=out-185.mta0.migadu.com
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_PASS=-0.001,
 T_SPF_TEMPERROR=0.01 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: 0.9 (/)
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.1 (/)

--=-=-=
Content-Type: text/plain

Pip, Gerd, Helmut,

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

WDYT?


--=-=-=
Content-Type: text/x-diff
Content-Disposition: attachment;
 filename=0001-lisp-emacs-lisp-igc.el-checkdox-fixes-for-interactiv.patch

From e803743e318260b82edc5838318ca5b80e33c45b Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@HIDDEN>
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


--=-=-=--

Message sent:

Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-Mailer: MIME-tools 5.505 (Entity 5.505)
Content-Type: text/plain; charset=utf-8
X-Loop: help-debbugs@HIDDEN
From: help-debbugs@HIDDEN (GNU bug Tracking System)
To: Jeremy Bryant <jb@HIDDEN>
Subject: bug#77142: Acknowledgement ([PATCH] ; * lisp/emacs-lisp/igc.el:
 checkdox fixes for interactive functions)
Message-ID: <handler.77142.B.174250966015420.ack <at> debbugs.gnu.org>
References: <87bjtvwd6z.fsf@HIDDEN>
X-Gnu-PR-Message: ack 77142
X-Gnu-PR-Package: emacs
X-Gnu-PR-Keywords: patch
Reply-To: 77142 <at> debbugs.gnu.org
Date: Thu, 20 Mar 2025 22:28:03 +0000

Thank you for filing a new bug report with debbugs.gnu.org.

This is an automatically generated reply to let you know your message
has been received.

Your message is being forwarded to the package maintainers and other
interested parties for their attention; they will reply in due course.

Your message has been sent to the package maintainer(s):
 bug-gnu-emacs@HIDDEN

If you wish to submit further information on this problem, please
send it to 77142 <at> debbugs.gnu.org.

Please do not send mail to help-debbugs@HIDDEN unless you wish
to report a problem with the Bug-tracking system.

--=20
77142: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D77142
GNU Bug Tracking System
Contact help-debbugs@HIDDEN with problems

Message sent to bug-gnu-emacs@HIDDEN:

Subject: bug#77142: [PATCH] ; * lisp/emacs-lisp/igc.el: checkdox fixes for interactive functions
Resent-From: Eli Zaretskii <eliz@HIDDEN>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@HIDDEN
Resent-Date: Sat, 22 Mar 2025 11:42:02 +0000
Resent-Message-ID: <handler.77142.B77142.174264367010629 <at> debbugs.gnu.org>
Resent-Sender: help-debbugs@HIDDEN
To: Jeremy Bryant <jb@HIDDEN>
Cc: gerd.moellmann@HIDDEN, pipcet@HIDDEN, eller.helmut@HIDDEN, 77142 <at> debbugs.gnu.org
Date: Sat, 22 Mar 2025 13:40:58 +0200
Message-Id: <86bjttjnsl.fsf@HIDDEN>
From: Eli Zaretskii <eliz@HIDDEN>
In-Reply-To: <87bjtvwd6z.fsf@HIDDEN> (bug-gnu-emacs@HIDDEN)
References: <87bjtvwd6z.fsf@HIDDEN>
Precedence: list
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>

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

Last modified: Sat, 22 Mar 2025 11:45:01 UTC

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