Received: (at 77142) by debbugs.gnu.org; 22 Mar 2025 11:41:10 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Mar 22 07:41:10 2025
Received: from localhost ([127.0.0.1]:41246 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1tvxDy-0002lN-46
for submit <at> debbugs.gnu.org; Sat, 22 Mar 2025 07:41:10 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10]:39250)
by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.84_2) (envelope-from <eliz@HIDDEN>) id 1tvxDw-0002lA-Oq
for 77142 <at> debbugs.gnu.org; Sat, 22 Mar 2025 07:41:09 -0400
Received: from fencepost.gnu.org ([2001:470:142:3::e])
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <eliz@HIDDEN>)
id 1tvxDq-0000fq-5K; Sat, 22 Mar 2025 07:41:03 -0400
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org;
s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date:
mime-version; bh=AfTz+go41gk0r4dRWPSLPuLs032XQ+uP8bz1TSX5zYg=; b=i5T8ZGclmmqW
xDC1mqdZ3/oNclZRNM48YSha/x1Rv62NBewvBSl1zzebJu1TfmjmRuL70GCqdKP+YeWr+yloKBRFM
tZOLAybdTX4kUOhK+OfHMsiypK+BWb9nbRizszzMkpskFNrS7MxJebZ+KYehg9r7KgZa07kncom42
yASQ83TKri/F0TK9glef45AWzH+3cSGBKw0AqRaQCK1Gm3u7U4joU1zSkLjJKXVw8vq5QsqhwMXUD
Ts0JD8RfBR2v17tQgQznVZrVUldXDgDimNcmOacixtxnuyKyR4MLjQnnapCl8VA/zz+RyovarP+WI
fNBuCopKEn6rN0f9DJ8PmA==;
Date: Sat, 22 Mar 2025 13:40:58 +0200
Message-Id: <86bjttjnsl.fsf@HIDDEN>
From: Eli Zaretskii <eliz@HIDDEN>
To: Jeremy Bryant <jb@HIDDEN>
In-Reply-To: <87bjtvwd6z.fsf@HIDDEN> (bug-gnu-emacs@HIDDEN)
Subject: Re: bug#77142: [PATCH] ;
* lisp/emacs-lisp/igc.el: checkdox fixes for interactive functions
References: <87bjtvwd6z.fsf@HIDDEN>
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 77142
Cc: gerd.moellmann@HIDDEN, pipcet@HIDDEN, eller.helmut@HIDDEN,
77142 <at> debbugs.gnu.org
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: -3.3 (---)
> 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 `...')
bug-gnu-emacs@HIDDEN:bug#77142; Package emacs.
Full text available.
Received: (at submit) by debbugs.gnu.org; 20 Mar 2025 22:27:40 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Mar 20 18:27:39 2025
Received: from localhost ([127.0.0.1]:59416 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1tvOMU-00040V-Rv
for submit <at> debbugs.gnu.org; Thu, 20 Mar 2025 18:27:39 -0400
Received: from lists.gnu.org ([2001:470:142::17]:48044)
by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.84_2) (envelope-from <jb@HIDDEN>)
id 1tvOMN-0003yh-Rh
for submit <at> debbugs.gnu.org; Thu, 20 Mar 2025 18:27:35 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10])
by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <jb@HIDDEN>)
id 1tvOMC-0001UK-18
for bug-gnu-emacs@HIDDEN; Thu, 20 Mar 2025 18:27:20 -0400
Received: from out-185.mta0.migadu.com ([2001:41d0:1004:224b::b9])
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <jb@HIDDEN>)
id 1tvOM1-0003LA-NI
for bug-gnu-emacs@HIDDEN; Thu, 20 Mar 2025 18:27:19 -0400
X-Report-Abuse: Please report any abuse attempt to abuse@HIDDEN and
include these headers.
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net;
s=key1; t=1742509622;
h=from:from:reply-to:subject:subject:date:date:message-id:message-id:
to:to:cc:mime-version:mime-version:content-type:content-type;
bh=W80Ra9ZEpCQZ36+cMJnU5aE+OGkKPSMNwA+1XKeWS8Y=;
b=KT4WKtpFIz8UOlFVh6F5Y3ChRKoPW93nNUwLL3YH3BKt/siGIO+/DvTENF+alnWQgu5/GQ
3sbC7d7wTD1Wx3io4xDq6+Ab4SDLEYY5isa+52KgXxapBvBo8vPAZS4+LbusOuBhXE0c8z
FPaWe1OGEpg9bIzk2XlhBbJmpNpfYGiosJAyJxo+X2tuM74n/EBt3B8AN/qbEu4dNLg4ML
+wn17pqe5NTpGPfUPLp5QNGq/lx68IB84L8iukGmxjtXnZUqruYZi+5QOoPL+S8ejFCNAT
G4uvyNAoyN//3WVcr8/M6hNeX8yKn+VeTaN5BnnEynD735Qr5YTYDkjRmza35Q==
From: Jeremy Bryant <jb@HIDDEN>
To: bug-gnu-emacs@HIDDEN, Pip Cet <pipcet@HIDDEN>, Gerd
=?utf-8?Q?M=C3=B6llmann?=
<gerd.moellmann@HIDDEN>, Helmut Eller <eller.helmut@HIDDEN>
Subject: [PATCH] ; * lisp/emacs-lisp/igc.el: checkdox fixes for interactive
functions
Date: Thu, 20 Mar 2025 22:27:00 +0000
Message-ID: <87bjtvwd6z.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="=-=-="
X-Migadu-Flow: FLOW_OUT
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-Debbugs-Envelope-To: submit
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
--=-=-=--
Jeremy Bryant <jb@HIDDEN>:bug-gnu-emacs@HIDDEN.
Full text available.bug-gnu-emacs@HIDDEN:bug#77142; Package emacs.
Full text available.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997 nCipher Corporation Ltd,
1994-97 Ian Jackson.