From unknown Sat Aug 16 19:17:10 2025 X-Loop: help-debbugs@gnu.org Subject: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 13 Nov 2023 22:43:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 67153 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: 67153@debbugs.gnu.org, rms@gnu.org, gerd@gnu.org, monnier@iro.umontreal.ca X-Debbugs-Original-To: bug-gnu-emacs@gnu.org, Richard Stallman , Gerd =?UTF-8?Q?M=C3=B6llmann?= , Stefan Monnier Received: via spool by submit@debbugs.gnu.org id=B.169991533222295 (code B ref -1); Mon, 13 Nov 2023 22:43:01 +0000 Received: (at submit) by debbugs.gnu.org; 13 Nov 2023 22:42:12 +0000 Received: from localhost ([127.0.0.1]:59461 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r2fdE-0005nX-BM for submit@debbugs.gnu.org; Mon, 13 Nov 2023 17:42:12 -0500 Received: from lists.gnu.org ([2001:470:142::17]:40788) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r2fdC-0005nC-MJ for submit@debbugs.gnu.org; Mon, 13 Nov 2023 17:42:11 -0500 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 ) id 1r2fcR-0005nx-GL for bug-gnu-emacs@gnu.org; Mon, 13 Nov 2023 17:41:23 -0500 Received: from out-171.mta1.migadu.com ([2001:41d0:203:375::ab]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r2fcJ-0003g1-Id for bug-gnu-emacs@gnu.org; Mon, 13 Nov 2023 17:41:23 -0500 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1699915271; 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=t4XdEwbiWHdRESvVO/MmzlcL7DiyvBkV7kHKCKjJwO4=; b=laaBkJl8m+mUFal1n44zXYC04QGkv3783e+EDlZEouPT3FlfGiqkcnFicCRvT579jQb+iF uGnUW4PZVVPUR+9Ns8eDzOst0Emx0CP8MGP+G3w5UTyAa1CcPjKQx79c8jXxpxYPib7le4 UxOqoyyxcQhWrAp9gI6ExCFxFg6vekgsFIegtQW8LfN8OY25+EhJRaEinSTMVNlKVf30F4 IgnSTcWu2uL85GowXXb0GBeuCGGaiLP8QkJLu9KmJHrGap/5Kqjydly6xADXR61PB5cEuG ntx6j7LhrIIW4WUHjqSPdB7LnRXds91o3nJS3MvLwCMtial2bsmPcdi7ZUlvEA== From: Jeremy Bryant Date: Mon, 13 Nov 2023 22:38:39 +0000 Message-ID: <87bkbx8ef0.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=2001:41d0:203:375::ab; envelope-from=jb@jeremybryant.net; helo=out-171.mta1.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_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) --=-=-= Content-Type: text/plain Tags: patch This patch adds 5 docstrings to abbrev.el where there were none before. This now completes all docstrings in this Lisp file. The patch is a documentation patch based on emacs-29. Please let me know if this is ready to install or if changes are needed. --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0002-Add-5-docstrings-to-abbrev.el.patch >From fbe88f6dd4717ae07883dfdf8e87053008293753 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Mon, 13 Nov 2023 22:24:36 +0000 Subject: [PATCH 2/2] Add 5 docstrings to abbrev.el * lisp/abbrev.el (prepare-abbrev-list-buffer) (add-abbrev) (inverse-add-abbrev) (abbrev--describe) (abbrev--possibly-save): Add docstrings. --- lisp/abbrev.el | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/lisp/abbrev.el b/lisp/abbrev.el index e1311dbc83b..70c79c1380f 100644 --- a/lisp/abbrev.el +++ b/lisp/abbrev.el @@ -122,6 +122,10 @@ abbrev-table-name found)) (defun prepare-abbrev-list-buffer (&optional local) + "Return *Abbrevs* buffer for the caller to select or display. + +LOCAL is a flag, if non-nil display only local abbrevs. +" (let ((local-table local-abbrev-table)) (with-current-buffer (get-buffer-create "*Abbrevs*") (erase-buffer) @@ -333,6 +337,22 @@ add-global-abbrev (add-abbrev global-abbrev-table "Global" arg)) (defun add-abbrev (table type arg) + "Define an abbrev in abbrev TABLE whose expansion is last word before point. +If there's an active region, use that as the expansion. + +ARG says how many words before point to use for the expansion; +zero means the entire region is the expansion. + +A negative ARG means to undefine the specified abbrev. + +TYPE of abbrev includes \"Global\", \"Mode\". + +This command reads the abbreviation from the minibuffer. + +See `add-global-abbrev', `add-mode-abbrev' for caller examples. +See `inverse-add-abbrev' for the opposite task. + +Don't use this function in a Lisp program; use `define-abbrev' instead." (let ((exp (cond ((or (and (null arg) (use-region-p)) @@ -393,6 +413,18 @@ inverse-add-global-abbrev (inverse-add-abbrev global-abbrev-table "Global" n)) (defun inverse-add-abbrev (table type arg) + "Define the word before point as as an abbrev in TABLE. + +ARG means use the ARG-th word before point as the +abbreviation. Negative ARG means use the ARG-th word after point. + +This command reads the expansion from the minibuffer, defines the +abbrev, and then expands the abbreviation in the current buffer. + +TYPE of abbrev can be \"Global\", \"Mode\". + +See `inverse-add-global-n', `inverse-add-mode-abbrev' for caller examples. +See also `add-abbrev', which performs the opposite task." (let (name exp start end) (save-excursion (forward-word (1+ (- arg))) @@ -406,7 +438,7 @@ inverse-add-abbrev nil nil nil t)) (when (or (not (abbrev-expansion name table)) (y-or-n-p (format "%s expands into \"%s\"; redefine? " - name (abbrev-expansion name table)))) + name (abbrev-expansion name table)))) (define-abbrev table (downcase name) exp) (save-excursion (goto-char end) @@ -1102,6 +1134,8 @@ abbrev--write (insert ")\n")) (defun abbrev--describe (sym) + "Describe abbrev SYM. +Used to generate a table by `insert-abbrev-table-description'." (when (symbol-value sym) (prin1 (symbol-name sym)) (if (null (abbrev-get sym :system)) @@ -1243,6 +1277,8 @@ edit-abbrevs-mode (setq font-lock-multiline nil)) (defun abbrev--possibly-save (query &optional arg) + "Hook function for use by `save-some-buffer-functions'. +Associated meaning for QUERY and ARG." ;; Query mode. (if (eq query 'query) (and save-abbrevs abbrevs-changed) -- 2.40.1 --=-=-=-- From unknown Sat Aug 16 19:17:10 2025 X-Loop: help-debbugs@gnu.org Subject: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 14 Nov 2023 14:20:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 67153 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Jeremy Bryant Cc: 67153@debbugs.gnu.org, gerd@gnu.org, rms@gnu.org, monnier@iro.umontreal.ca Received: via spool by 67153-submit@debbugs.gnu.org id=B67153.169997154622474 (code B ref 67153); Tue, 14 Nov 2023 14:20:01 +0000 Received: (at 67153) by debbugs.gnu.org; 14 Nov 2023 14:19:06 +0000 Received: from localhost ([127.0.0.1]:60635 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r2uFu-0005qP-6K for submit@debbugs.gnu.org; Tue, 14 Nov 2023 09:19:06 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:41298) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r2uFs-0005ps-1m for 67153@debbugs.gnu.org; Tue, 14 Nov 2023 09:19:04 -0500 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 ) id 1r2uF3-0003Yi-Dg; Tue, 14 Nov 2023 09:18:14 -0500 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=Nzex+bEusNmy7bTHWyabOk/6yae/8PI9CsgKULE4B8Y=; b=fXof6RojyNpb YUUT0VXQVTF+lxKuRNeMiaz5xu56W21pT7QOqmtw4c0L9J4RrTuvzbKi3qVhcciOoZq/dyXXsBugB heZoG5buQVhExcjoA+74MyNhJrEdyjKn2yuvokGvJVE3mWOVtUdczUVjlloK7VNL938xhrWksyWUu 8kMXXHjJ7AU4dMho95/Sm2VYnLKF99B6r7w34Lq6NfetpnKtFOEvNl5pG55fZpw7IYIuCcrStzNg6 1kqHG+m5jAMqjsYmbzDNF1hxi31Q/7CmnTg/UTIlzny5CIT5fvQLPbdCt/h7Nj5jrB4X8k7BtWfyS 8uLskKmSHYQP2zXqRoDr0A==; Date: Tue, 14 Nov 2023 16:17:54 +0200 Message-Id: <83v8a4s9kd.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87bkbx8ef0.fsf@jeremybryant.net> (bug-gnu-emacs@gnu.org) References: <87bkbx8ef0.fsf@jeremybryant.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Date: Mon, 13 Nov 2023 22:38:39 +0000 > From: Jeremy Bryant via "Bug reports for GNU Emacs, > the Swiss army knife of text editors" > > This patch adds 5 docstrings to abbrev.el where there were none before. > This now completes all docstrings in this Lisp file. > > The patch is a documentation patch based on emacs-29. > Please let me know if this is ready to install or if changes are needed. Thanks, see a few comments below. > (defun prepare-abbrev-list-buffer (&optional local) > + "Return *Abbrevs* buffer for the caller to select or display. > + > +LOCAL is a flag, if non-nil display only local abbrevs. > +" That newline before the closing quote is redundant, > (defun add-abbrev (table type arg) > + "Define an abbrev in abbrev TABLE whose expansion is last word before point. The first sentence of a doc string should preferably mention the mandatory arguments (TYPE and ARG). If the result is too long to fit on a single line, consider saying only the main part there, and then describing the details in the following lines. > +TYPE of abbrev includes \"Global\", \"Mode\". "Includes"? are there other types? > (defun inverse-add-abbrev (table type arg) > + "Define the word before point as as an abbrev in TABLE. ^^^^^ Typo. > +ARG means use the ARG-th word before point as the > +abbreviation. Negative ARG means use the ARG-th word after point. > + > +This command reads the expansion from the minibuffer, defines the > +abbrev, and then expands the abbreviation in the current buffer. > + > +TYPE of abbrev can be \"Global\", \"Mode\". > + > +See `inverse-add-global-n', `inverse-add-mode-abbrev' for caller examples. > +See also `add-abbrev', which performs the opposite task." Same comments here. From unknown Sat Aug 16 19:17:10 2025 X-Loop: help-debbugs@gnu.org Subject: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el Resent-From: Stefan Monnier Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 14 Nov 2023 19:27:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 67153 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Jeremy Bryant Cc: gerd@gnu.org, 67153@debbugs.gnu.org, rms@gnu.org X-Debbugs-Original-Cc: Gerd =?UTF-8?Q?M=C3=B6llmann?= , bug-gnu-emacs@gnu.org, Richard Stallman Received: via spool by submit@debbugs.gnu.org id=B.169998999421723 (code B ref -1); Tue, 14 Nov 2023 19:27:02 +0000 Received: (at submit) by debbugs.gnu.org; 14 Nov 2023 19:26:34 +0000 Received: from localhost ([127.0.0.1]:34182 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r2z3S-0005eI-BF for submit@debbugs.gnu.org; Tue, 14 Nov 2023 14:26:34 -0500 Received: from lists.gnu.org ([2001:470:142::17]:57856) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r2z3Q-0005e5-VM for submit@debbugs.gnu.org; Tue, 14 Nov 2023 14:26:33 -0500 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 ) id 1r2z2e-0003Bm-Jx for bug-gnu-emacs@gnu.org; Tue, 14 Nov 2023 14:25:44 -0500 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r2z2c-0006qX-Ff; Tue, 14 Nov 2023 14:25:44 -0500 Received: from pmg2.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 594C1807BC; Tue, 14 Nov 2023 14:25:37 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1699989936; bh=Rna7XfD8Ea5PQDhxIaomV92mDOvS4OLZ8FE58E9hlUA=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=j3IDkwNI0BxT6YSJ5kbYF2TQ4WNW6ABeaXZ3t2KBMsJkOQ1DvU3wENElFIi6Ch60x FGNwoA/dYCOlqcjCnQWjVz3jQUatuv7wPr0IkjRRD7Ni9r4B2DBwdeQcLXfJ8GdTm9 jNV7HXA9ick4pBPWrERvPeH+AJKErHl/gvYn1qSqBYtpYUdohrn6CvkWycvz8XLb1o v6dO/VgKuN+4bzmWQAJ7UUhUBke+PnqiCsoXLTvXTQ8JzPI43nI0+OsqhvYuitzt/A L5HPzs15d+hbe/dwmsPkvAGoC81GzpER4yFIkdR2BzHdowYgUSTfZZJFu/3jmI5p03 KocVAnv8JffbA== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 710CD80098; Tue, 14 Nov 2023 14:25:36 -0500 (EST) Received: from lechazo (lechon.iro.umontreal.ca [132.204.27.242]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 5845C1203C5; Tue, 14 Nov 2023 14:25:36 -0500 (EST) From: Stefan Monnier In-Reply-To: <87bkbx8ef0.fsf@jeremybryant.net> (Jeremy Bryant's message of "Mon, 13 Nov 2023 22:38:39 +0000") Message-ID: References: <87bkbx8ef0.fsf@jeremybryant.net> Date: Tue, 14 Nov 2023 14:23:01 -0500 User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-SPAM-INFO: Spam detection results: 0 ALL_TRUSTED -1 Passed through trusted hosts only via SMTP AWL 0.091 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain T_SCC_BODY_TEXT_LINE -0.01 - X-SPAM-LEVEL: Received-SPF: pass client-ip=132.204.25.50; envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca X-Spam_score_int: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) > This patch adds 5 docstrings to abbrev.el where there were none before. Thanks. See some comments below. Stefan > (defun prepare-abbrev-list-buffer (&optional local) > + "Return *Abbrevs* buffer for the caller to select or display. A few points: - I don't think the docstring should document to the name of the buffer. - Docstrings should usually say what the function does rather than what the callers are expected to do with the result. - To me, the above description makes it sound like the function does little more than `(get-buffer "*Abbrevs*")`. IOW, it should say that it fills the buffer with "some" representation of "some" abbrevs. > +LOCAL is a flag, if non-nil display only local abbrevs. > +" We don't like our docstrings to end with a newline. > +A negative ARG means to undefine the specified abbrev. [...] > +This command reads the abbreviation from the minibuffer. We should say this before referring to it via "the specified abbrev". > +TYPE of abbrev includes \"Global\", \"Mode\". Here you made the same mistake of documenting what the callers do rather than what the function does. > +See `add-global-abbrev', `add-mode-abbrev' for caller examples. We usually don't include this in docstrings. We have `xref` and `grep` for those kinds of things. > (defun abbrev--describe (sym) > + "Describe abbrev SYM. > +Used to generate a table by `insert-abbrev-table-description'." Similarly here I wouldn't mention the caller. Instead I'd try and explain what kind of description is generated and where it's placed (at point in the current buffer? As a return values? ...). > (defun abbrev--possibly-save (query &optional arg) > + "Hook function for use by `save-some-buffer-functions'. > +Associated meaning for QUERY and ARG." Hook functions are one of the exceptions where it's often OK to refer to how it's used in the docstring, like you do here (e.g. so we don't have to repeat what `query` and `arg` are for). But it should also say what it actually does. Stefan From unknown Sat Aug 16 19:17:10 2025 X-Loop: help-debbugs@gnu.org Subject: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 15 Nov 2023 23:32:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 67153 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Stefan Monnier Cc: gerd@gnu.org, 67153@debbugs.gnu.org, rms@gnu.org X-Debbugs-Original-Cc: Gerd =?UTF-8?Q?M=C3=B6llmann?= , bug-gnu-emacs@gnu.org, Richard Stallman Received: via spool by submit@debbugs.gnu.org id=B.170009111919174 (code B ref -1); Wed, 15 Nov 2023 23:32:02 +0000 Received: (at submit) by debbugs.gnu.org; 15 Nov 2023 23:31:59 +0000 Received: from localhost ([127.0.0.1]:54154 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3PMV-0004zB-9I for submit@debbugs.gnu.org; Wed, 15 Nov 2023 18:31:59 -0500 Received: from lists.gnu.org ([2001:470:142::17]:39976) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3PMR-0004yu-Ry for submit@debbugs.gnu.org; Wed, 15 Nov 2023 18:31:58 -0500 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 ) id 1r3PMN-0005Gw-7s for bug-gnu-emacs@gnu.org; Wed, 15 Nov 2023 18:31:51 -0500 Received: from out-180.mta0.migadu.com ([91.218.175.180]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r3PMK-0004q6-E6 for bug-gnu-emacs@gnu.org; Wed, 15 Nov 2023 18:31:50 -0500 References: <87bkbx8ef0.fsf@jeremybryant.net> DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1700091104; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=EWKWRIOCrMbMKTrwhc8AaZWNX8kWnmX1N3EoB4g5C08=; b=ZYHlbdf2Q1p2zv7vQ1OL0SRFs1V2lWNvAP0eub2PkeEcwgbySn03UUm/LOOJI8Sn9HSJqC o3MINqCDTCN3XNeA88ewe2/v509td2JIw9+0g02RD20Yy7mykKmyimJmJCzKKSuefX0Ri7 cfJgZ+T6MFZ1nklbKJJlg2e5Ur4P3AyP+rByks5W/Y19ktcYzody7wxsPWodUj00OnRnps JrSCWeybRuDGZq1mJcTU9Pu/VXfZOlYkd8Bsl1v3vEzgStWKw9HDSXp+paVRit1J1o9rdb tFtLubD39/tK6uDUwUPjgVeaSJ3/zrok3M1rZa0NgB7v12NZ4PO47pEuT1ErqQ== X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. From: Jeremy Bryant Date: Wed, 15 Nov 2023 23:24:48 +0000 In-reply-to: Message-ID: <878r6yvbj5.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=91.218.175.180; envelope-from=jb@jeremybryant.net; helo=out-180.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_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Add-5-docstrings-to-abbrev.el.patch >From 2e7f167ae4c6cac02d530a1c9d529c3240eb4187 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Wed, 15 Nov 2023 23:15:46 +0000 Subject: [PATCH] Add 5 docstrings to abbrev.el * lisp/abbrev.el (prepare-abbrev-list-buffer) (add-abbrev) (inverse-add-abbrev) (abbrev--describe) (abbrev--possibly-save): Add docstrings. --- lisp/abbrev.el | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/lisp/abbrev.el b/lisp/abbrev.el index e1311dbc83b..6f62e088d64 100644 --- a/lisp/abbrev.el +++ b/lisp/abbrev.el @@ -122,6 +122,9 @@ abbrev-table-name found)) (defun prepare-abbrev-list-buffer (&optional local) + "Return buffer listing abbreviations and expansions for each abbrev table. + +LOCAL is a flag, if non-nil display only local abbrevs." (let ((local-table local-abbrev-table)) (with-current-buffer (get-buffer-create "*Abbrevs*") (erase-buffer) @@ -333,6 +336,21 @@ add-global-abbrev (add-abbrev global-abbrev-table "Global" arg)) (defun add-abbrev (table type arg) + "Define abbrev in TABLE, whose expansion is ARG words before point. +This command reads the abbreviation from the minibuffer, with prompt TYPE. + +ARG of zero means the entire region is the expansion. +If there's an active region, use that as the expansion. + +A negative ARG means to undefine the specified abbrev. + +TYPE is an arbitrary string used to prompt user for the kind of +abbrev, such as \"Global\", \"Mode\". (This has no influence on the +choice of the actual TABLE). + +See `inverse-add-abbrev' for the opposite task. + +Don't use this function in a Lisp program; use `define-abbrev' instead." (let ((exp (cond ((or (and (null arg) (use-region-p)) @@ -353,7 +371,7 @@ add-abbrev (if (or (null exp) (not (abbrev-expansion name table)) (y-or-n-p (format "%s expands into \"%s\"; redefine? " - name (abbrev-expansion name table)))) + name (abbrev-expansion name table)))) (define-abbrev table (downcase name) exp)))) (defun inverse-add-mode-abbrev (n) @@ -393,6 +411,18 @@ inverse-add-global-abbrev (inverse-add-abbrev global-abbrev-table "Global" n)) (defun inverse-add-abbrev (table type arg) + "Define the word before point as an abbrev in TABLE. +This command reads the expansion from the minibuffer, using prompt TYPE, +defines the abbrev, and then expands the abbreviation in the current buffer. + +ARG means use the ARG-th word before point as the abbreviation. +Negative ARG means use the ARG-th word after point. + +TYPE is an arbitrary string used to prompt user for the kind of +abbrev, such as \"Global\", \"Mode\". (This has no influence on the +choice of the actual TABLE). + +See also `add-abbrev', which performs the opposite task." (let (name exp start end) (save-excursion (forward-word (1+ (- arg))) @@ -1102,6 +1132,8 @@ abbrev--write (insert ")\n")) (defun abbrev--describe (sym) + "Describe abbrev SYM. +Print on `standard-output' the abbrev, count of use, expansion." (when (symbol-value sym) (prin1 (symbol-name sym)) (if (null (abbrev-get sym :system)) @@ -1243,6 +1275,8 @@ edit-abbrevs-mode (setq font-lock-multiline nil)) (defun abbrev--possibly-save (query &optional arg) + "Maybe save abbrevs: Hook function for use by `save-some-buffer-functions'. +Associated meaning for QUERY and ARG." ;; Query mode. (if (eq query 'query) (and save-abbrevs abbrevs-changed) -- 2.40.1 --=-=-= Content-Type: text/plain Attached is a revised patch addressing comments of Eli and Stefan. Further clarifications below:- Stefan Monnier writes: >> (defun prepare-abbrev-list-buffer (&optional local) >> + "Return *Abbrevs* buffer for the caller to select or display. > > A few points: > > - I don't think the docstring should document to the name of the buffer. > - Docstrings should usually say what the function does rather than what > the callers are expected to do with the result. Initially, I had simply lifted the text from the file ChangeLog.1 1985-12-13 Richard M. Stallman (rms@prep) * abbrev.el (prepare-abbrev-list-buffer, list-abbrevs, edit-abbrevs): Some cleanups. prepare-... now does all the work and returns the buffer for the caller to select or display. But I have now rewritten. > - To me, the above description makes it sound like the function does > little more than `(get-buffer "*Abbrevs*")`. > IOW, it should say that it fills the buffer with "some" representation > of "some" abbrevs. > >> +LOCAL is a flag, if non-nil display only local abbrevs. >> +" > > We don't like our docstrings to end with a newline. Fixed. > >> +A negative ARG means to undefine the specified abbrev. > [...] >> +This command reads the abbreviation from the minibuffer. > > We should say this before referring to it via "the specified abbrev". Fixed in both add-abbrev and inverse-add-abbrev. I initially adapted the docstring from surrounding callers like add-global-abbrev, but have now rewritten. > >> +TYPE of abbrev includes \"Global\", \"Mode\". > > Here you made the same mistake of documenting what the callers do rather > than what the function does. Fixed, rewritten, it turns out the ARG string is purely descriptive. > >> +See `add-global-abbrev', `add-mode-abbrev' for caller examples. > > We usually don't include this in docstrings. > We have `xref` and `grep` for those kinds of things. Fixed >> (defun abbrev--describe (sym) >> + "Describe abbrev SYM. >> +Used to generate a table by `insert-abbrev-table-description'." > > Similarly here I wouldn't mention the caller. Instead I'd try and > explain what kind of description is generated and where it's placed > (at point in the current buffer? As a return values? ...). Fixed with this detail after examining the code. > >> (defun abbrev--possibly-save (query &optional arg) >> + "Hook function for use by `save-some-buffer-functions'. >> +Associated meaning for QUERY and ARG." > > Hook functions are one of the exceptions where it's often OK to refer to > how it's used in the docstring, like you do here (e.g. so we don't have > to repeat what `query` and `arg` are for). > But it should also say what it actually does. Fixed. > > > Stefan --=-=-=-- From unknown Sat Aug 16 19:17:10 2025 X-Loop: help-debbugs@gnu.org Subject: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 16 Nov 2023 06:48:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 67153 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Jeremy Bryant Cc: 67153@debbugs.gnu.org, monnier@iro.umontreal.ca Received: via spool by 67153-submit@debbugs.gnu.org id=B67153.17001172541835 (code B ref 67153); Thu, 16 Nov 2023 06:48:01 +0000 Received: (at 67153) by debbugs.gnu.org; 16 Nov 2023 06:47:34 +0000 Received: from localhost ([127.0.0.1]:54392 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3WA1-0000TU-VB for submit@debbugs.gnu.org; Thu, 16 Nov 2023 01:47:34 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:38264) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3WA0-0000T7-8h for 67153@debbugs.gnu.org; Thu, 16 Nov 2023 01:47:33 -0500 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 ) id 1r3W9v-0005bV-8l; Thu, 16 Nov 2023 01:47:27 -0500 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=gzzeEGVCCoKsEpqGR4X4JqS0kjTbqa5qD8qsJDOphtY=; b=YCMmf4AneR4F JMFTNeiumO+GMvwGURAWxKi40nCbvVBQgCvf8SUGH1DdQqyLI3o03i2jfU3ajwcFMjvS3+oAXyD5d POl5mmxi54Y1Eidg3uhr5ecfTZfxJ2dqaARtAwAq2Ykm0R6UCv6R/V68RDFfI89Qc2GJpzbTduhVi WMk3scf9RHYGoroSviZNz6ySFbmD6QGHAkEO7ZBqYo2sRhLSrrW0JPBz/8NLItvavc53Dwi5LXtEi rxNGPx+uVn3HhY65GTUEfuDzsN420mL4M8kc2rwI4cw7UZnSgSVGDotNFRlD+81cnW77VGg5+F8rP klfTsF2PxXsYvWMSrQDDhw==; Date: Thu, 16 Nov 2023 08:47:18 +0200 Message-Id: <83v8a2p53d.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <878r6yvbj5.fsf@jeremybryant.net> (bug-gnu-emacs@gnu.org) References: <87bkbx8ef0.fsf@jeremybryant.net> <878r6yvbj5.fsf@jeremybryant.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Cc: gerd@gnu.org, 67153@debbugs.gnu.org, rms@gnu.org > Date: Wed, 15 Nov 2023 23:24:48 +0000 > From: Jeremy Bryant via "Bug reports for GNU Emacs, > the Swiss army knife of text editors" > > (defun prepare-abbrev-list-buffer (&optional local) > + "Return buffer listing abbreviations and expansions for each abbrev table. > + > +LOCAL is a flag, if non-nil display only local abbrevs." Our style for expressing what you say in the last sentence is If LOCAL is non-nil, include in the buffer only the local abbrevs. ("Display" is not appropriate here, since this function doesn't display the buffer.) > (defun add-abbrev (table type arg) > + "Define abbrev in TABLE, whose expansion is ARG words before point. > +This command reads the abbreviation from the minibuffer, with prompt TYPE. ^^^^^^^ This is not a command. > +ARG of zero means the entire region is the expansion. > +If there's an active region, use that as the expansion. Is the second sentence conditioned on the first, i.e., does the function use the active region only when ARG is zero? If so, the second sentence should be removed. If use of the active region is NOT conditioned on ARG, I would reword the above: If there's an active region, use the region as the expansion. ARG of zero means the region is the expansion, even if it is inactive. > (defun inverse-add-abbrev (table type arg) > + "Define the word before point as an abbrev in TABLE. > +This command reads the expansion from the minibuffer, using prompt TYPE, > +defines the abbrev, and then expands the abbreviation in the current buffer. > + > +ARG means use the ARG-th word before point as the abbreviation. > +Negative ARG means use the ARG-th word after point. > + > +TYPE is an arbitrary string used to prompt user for the kind of > +abbrev, such as \"Global\", \"Mode\". (This has no influence on the > +choice of the actual TABLE). > + > +See also `add-abbrev', which performs the opposite task." Same comments here. > (defun abbrev--possibly-save (query &optional arg) > + "Maybe save abbrevs: Hook function for use by `save-some-buffer-functions'. I'd say here just Hook function for use by `save-some-buffer-functions'. and add the "Maybe save" bit as a separate second sentence. > +Associated meaning for QUERY and ARG." I couldn't parse this sentence. Thanks. From unknown Sat Aug 16 19:17:10 2025 X-Loop: help-debbugs@gnu.org Subject: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 16 Nov 2023 23:56:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 67153 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Eli Zaretskii Cc: 67153@debbugs.gnu.org, monnier@iro.umontreal.ca Received: via spool by 67153-submit@debbugs.gnu.org id=B67153.170017891920558 (code B ref 67153); Thu, 16 Nov 2023 23:56:04 +0000 Received: (at 67153) by debbugs.gnu.org; 16 Nov 2023 23:55:19 +0000 Received: from localhost ([127.0.0.1]:44831 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3mCc-0005LV-FJ for submit@debbugs.gnu.org; Thu, 16 Nov 2023 18:55:19 -0500 Received: from out-172.mta0.migadu.com ([91.218.175.172]:25877) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3mCQ-0005Kx-OR for 67153@debbugs.gnu.org; Thu, 16 Nov 2023 18:55:11 -0500 References: <87bkbx8ef0.fsf@jeremybryant.net> <878r6yvbj5.fsf@jeremybryant.net> <83v8a2p53d.fsf@gnu.org> DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1700178905; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=iEwSq1n6NRhUdztm7/lV/R+RUYnk2GUuotf7U6ZbdAE=; b=BRo3oT8nldBWpy2yZIb/IcCXXN3BtX4N2P5758prYnL9Ex+kDxx2aHVQq+Vz2xpzuzi1R+ 4FsuSn2//LCZElB2eaIa1VyhFs4OYSzLCZMcoANJZxCL3m73dPtDX3hGu3vIlcZaaxMV43 Xlyz1t1f5b5R+iXJE0GeE59VnshEwdd35w2e+s46A3Bsnuu6abkR3oYrAETR7BOLkLP8nH xop3B5gsmV2X1blYujy1R2yPLsobu9kE8/b04A06Uf/sNqn8WQf9sjPaJ0ALjuzeD7Qc/C Xgo26kVR8dxwj8HD1ieKjinNLeNaj1aw7BHw9VBapvKg1eK/VwfGa+lsCFGM1g== X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. From: Jeremy Bryant Date: Thu, 16 Nov 2023 23:48:04 +0000 In-reply-to: <83v8a2p53d.fsf@gnu.org> Message-ID: <87zfzdtfsa.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Add-5-docstrings-to-abbrev.el.patch >From a8a1b01cab209d73dabf34fe7fcebe9075bc3ca0 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Wed, 15 Nov 2023 23:15:46 +0000 Subject: [PATCH] Add 5 docstrings to abbrev.el * lisp/abbrev.el (prepare-abbrev-list-buffer) (add-abbrev) (inverse-add-abbrev) (abbrev--describe) (abbrev--possibly-save): Add docstrings. --- lisp/abbrev.el | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/lisp/abbrev.el b/lisp/abbrev.el index e1311dbc83b..6269fd50adf 100644 --- a/lisp/abbrev.el +++ b/lisp/abbrev.el @@ -122,6 +122,9 @@ abbrev-table-name found)) (defun prepare-abbrev-list-buffer (&optional local) + "Return buffer listing abbreviations and expansions for each abbrev table. + +If LOCAL is non-nil, include in the buffer only the local abbrevs." (let ((local-table local-abbrev-table)) (with-current-buffer (get-buffer-create "*Abbrevs*") (erase-buffer) @@ -333,6 +336,20 @@ add-global-abbrev (add-abbrev global-abbrev-table "Global" arg)) (defun add-abbrev (table type arg) + "Define abbrev in TABLE, whose expansion is ARG words before point. +Read the abbreviation from the minibuffer, with prompt TYPE. + +ARG of zero means the entire region is the expansion. + +A negative ARG means to undefine the specified abbrev. + +TYPE is an arbitrary string used to prompt user for the kind of +abbrev, such as \"Global\", \"Mode\". (This has no influence on the +choice of the actual TABLE). + +See `inverse-add-abbrev' for the opposite task. + +Don't use this function in a Lisp program; use `define-abbrev' instead." (let ((exp (cond ((or (and (null arg) (use-region-p)) @@ -353,7 +370,7 @@ add-abbrev (if (or (null exp) (not (abbrev-expansion name table)) (y-or-n-p (format "%s expands into \"%s\"; redefine? " - name (abbrev-expansion name table)))) + name (abbrev-expansion name table)))) (define-abbrev table (downcase name) exp)))) (defun inverse-add-mode-abbrev (n) @@ -393,6 +410,19 @@ inverse-add-global-abbrev (inverse-add-abbrev global-abbrev-table "Global" n)) (defun inverse-add-abbrev (table type arg) + "Define the word before point as an abbrev in TABLE. +Read the expansion from the minibuffer, using prompt TYPE, define +the abbrev, and then expand the abbreviation in the current +buffer. + +ARG means use the ARG-th word before point as the abbreviation. +Negative ARG means use the ARG-th word after point. + +TYPE is an arbitrary string used to prompt user for the kind of +abbrev, such as \"Global\", \"Mode\". (This has no influence on the +choice of the actual TABLE). + +See also `add-abbrev', which performs the opposite task." (let (name exp start end) (save-excursion (forward-word (1+ (- arg))) @@ -1102,6 +1132,8 @@ abbrev--write (insert ")\n")) (defun abbrev--describe (sym) + "Describe abbrev SYM. +Print on `standard-output' the abbrev, count of use, expansion." (when (symbol-value sym) (prin1 (symbol-name sym)) (if (null (abbrev-get sym :system)) @@ -1243,11 +1275,12 @@ edit-abbrevs-mode (setq font-lock-multiline nil)) (defun abbrev--possibly-save (query &optional arg) + "Hook function for use by `save-some-buffer-functions'. + +Maybe save abbrevs, and record whether we either saved them or asked to." ;; Query mode. (if (eq query 'query) (and save-abbrevs abbrevs-changed) - ;; Maybe save abbrevs, and record whether we either saved them or - ;; asked to. (and save-abbrevs abbrevs-changed (prog1 -- 2.40.1 --=-=-= Content-Type: text/plain Thank you for your patience in explaining what is required. New patch attached, with comments below. Eli Zaretskii writes: >> Cc: gerd@gnu.org, 67153@debbugs.gnu.org, rms@gnu.org >> Date: Wed, 15 Nov 2023 23:24:48 +0000 >> From: Jeremy Bryant via "Bug reports for GNU Emacs, >> the Swiss army knife of text editors" >> >> (defun prepare-abbrev-list-buffer (&optional local) >> + "Return buffer listing abbreviations and expansions for each abbrev table. >> + >> +LOCAL is a flag, if non-nil display only local abbrevs." > > Our style for expressing what you say in the last sentence is > > If LOCAL is non-nil, include in the buffer only the local abbrevs. > > ("Display" is not appropriate here, since this function doesn't > display the buffer.) Noted, fixed > >> (defun add-abbrev (table type arg) >> + "Define abbrev in TABLE, whose expansion is ARG words before point. >> +This command reads the abbreviation from the minibuffer, with prompt TYPE. > ^^^^^^^ > This is not a command. Reworded > >> +ARG of zero means the entire region is the expansion. >> +If there's an active region, use that as the expansion. > > Is the second sentence conditioned on the first, i.e., does the > function use the active region only when ARG is zero? If so, the > second sentence should be removed. If use of the active region is NOT > conditioned on ARG, I would reword the above: > > If there's an active region, use the region as the expansion. > ARG of zero means the region is the expansion, even if it is > inactive. > Fixed by removing sentence >> (defun inverse-add-abbrev (table type arg) >> + "Define the word before point as an abbrev in TABLE. >> +This command reads the expansion from the minibuffer, using prompt TYPE, >> +defines the abbrev, and then expands the abbreviation in the current buffer. >> + >> +ARG means use the ARG-th word before point as the abbreviation. >> +Negative ARG means use the ARG-th word after point. >> + >> +TYPE is an arbitrary string used to prompt user for the kind of >> +abbrev, such as \"Global\", \"Mode\". (This has no influence on the >> +choice of the actual TABLE). >> + >> +See also `add-abbrev', which performs the opposite task." > > Same comments here. Reworded; region comment N/A. > >> (defun abbrev--possibly-save (query &optional arg) >> + "Maybe save abbrevs: Hook function for use by `save-some-buffer-functions'. > > I'd say here just > > Hook function for use by `save-some-buffer-functions'. > > and add the "Maybe save" bit as a separate second sentence. Reworded by moving comment. > >> +Associated meaning for QUERY and ARG." > > I couldn't parse this sentence. > > Thanks. Initially I read Stefan's suggestion " Hook functions are one of the exceptions where it's often OK to refer to how it's used in the docstring, like you do here (e.g. so we don't have to repeat what `query` and `arg` are for). But it should also say what it actually does. " and left this as guide to arguments, but have now removed arguments entirely. Please let me know if this is good to install or any other changes needed. --=-=-=-- From unknown Sat Aug 16 19:17:10 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Jeremy Bryant Subject: bug#67153: closed (Re: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el) Message-ID: References: <83zfzcoktz.fsf@gnu.org> <87bkbx8ef0.fsf@jeremybryant.net> X-Gnu-PR-Message: they-closed 67153 X-Gnu-PR-Package: emacs X-Gnu-PR-Keywords: patch Reply-To: 67153@debbugs.gnu.org Date: Fri, 17 Nov 2023 08:18:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1700209082-13524-1" This is a multi-part message in MIME format... ------------=_1700209082-13524-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #67153: [PATCH 2/2] Add 5 docstrings to abbrev.el 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 67153@debbugs.gnu.org. --=20 67153: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D67153 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1700209082-13524-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 67153-done) by debbugs.gnu.org; 17 Nov 2023 08:17:30 +0000 Received: from localhost ([127.0.0.1]:45067 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3u2b-0003VF-Ja for submit@debbugs.gnu.org; Fri, 17 Nov 2023 03:17:29 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:46022) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3u2Y-0003V1-Fe for 67153-done@debbugs.gnu.org; Fri, 17 Nov 2023 03:17:28 -0500 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 ) id 1r3u2R-0005sz-Lo; Fri, 17 Nov 2023 03:17:19 -0500 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=ozHf9anVEFp02TX9KA3KOr11kto5KlUnpNxcW54n9O8=; b=Ui1XijXhaSxE iD/KfPA00TZAod86PRxkybUkiC0gZRhhD1mO055PeIn+ta9sFBI7UbXtv9YFtPvTe7jFOGGLQTE4D lKTnhvVCdRaU4R7FLEEJ1x44QeCN2Q+6IzKn4BS6eALO4TxD5Py6+Eh4nU8mQHQxHk8KkSIY5RHrN 8EVafSEknq8Rdk90dCdaBXO5L/XdBjop47MZYrq5xjrIdjI7knRn/KxxOGlkdimdPi5i5Re58lVYi GBGriAJ3COxydyITiEzqsJPqeSrxj0dD+zr8U1t8eqjXLbdrqDQvqqVpKKgjie81nb03Q90sO2DmX 7lfrd0WEL/TyHgR3OfEjZg==; Date: Fri, 17 Nov 2023 10:17:12 +0200 Message-Id: <83zfzcoktz.fsf@gnu.org> From: Eli Zaretskii To: Jeremy Bryant In-Reply-To: <87zfzdtfsa.fsf@jeremybryant.net> (message from Jeremy Bryant on Thu, 16 Nov 2023 23:48:04 +0000) Subject: Re: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el References: <87bkbx8ef0.fsf@jeremybryant.net> <878r6yvbj5.fsf@jeremybryant.net> <83v8a2p53d.fsf@gnu.org> <87zfzdtfsa.fsf@jeremybryant.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 67153-done Cc: 67153-done@debbugs.gnu.org, monnier@iro.umontreal.ca X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Jeremy Bryant > Cc: monnier@iro.umontreal.ca, 67153@debbugs.gnu.org > Date: Thu, 16 Nov 2023 23:48:04 +0000 > > Thank you for your patience in explaining what is required. > New patch attached, with comments below. Thanks, installed on the emacs-29 branch, and closing the bug. Please note my minor changes in the log message, and try to follow these conventions in the future. ------------=_1700209082-13524-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 13 Nov 2023 22:42:12 +0000 Received: from localhost ([127.0.0.1]:59461 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r2fdE-0005nX-BM for submit@debbugs.gnu.org; Mon, 13 Nov 2023 17:42:12 -0500 Received: from lists.gnu.org ([2001:470:142::17]:40788) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r2fdC-0005nC-MJ for submit@debbugs.gnu.org; Mon, 13 Nov 2023 17:42:11 -0500 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 ) id 1r2fcR-0005nx-GL for bug-gnu-emacs@gnu.org; Mon, 13 Nov 2023 17:41:23 -0500 Received: from out-171.mta1.migadu.com ([2001:41d0:203:375::ab]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r2fcJ-0003g1-Id for bug-gnu-emacs@gnu.org; Mon, 13 Nov 2023 17:41:23 -0500 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1699915271; 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=t4XdEwbiWHdRESvVO/MmzlcL7DiyvBkV7kHKCKjJwO4=; b=laaBkJl8m+mUFal1n44zXYC04QGkv3783e+EDlZEouPT3FlfGiqkcnFicCRvT579jQb+iF uGnUW4PZVVPUR+9Ns8eDzOst0Emx0CP8MGP+G3w5UTyAa1CcPjKQx79c8jXxpxYPib7le4 UxOqoyyxcQhWrAp9gI6ExCFxFg6vekgsFIegtQW8LfN8OY25+EhJRaEinSTMVNlKVf30F4 IgnSTcWu2uL85GowXXb0GBeuCGGaiLP8QkJLu9KmJHrGap/5Kqjydly6xADXR61PB5cEuG ntx6j7LhrIIW4WUHjqSPdB7LnRXds91o3nJS3MvLwCMtial2bsmPcdi7ZUlvEA== From: Jeremy Bryant To: bug-gnu-emacs@gnu.org, Richard Stallman , Gerd =?utf-8?Q?M=C3=B6llmann?= , Stefan Monnier Subject: [PATCH 2/2] Add 5 docstrings to abbrev.el Date: Mon, 13 Nov 2023 22:38:39 +0000 Message-ID: <87bkbx8ef0.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=2001:41d0:203:375::ab; envelope-from=jb@jeremybryant.net; helo=out-171.mta1.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_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) --=-=-= Content-Type: text/plain Tags: patch This patch adds 5 docstrings to abbrev.el where there were none before. This now completes all docstrings in this Lisp file. The patch is a documentation patch based on emacs-29. Please let me know if this is ready to install or if changes are needed. --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0002-Add-5-docstrings-to-abbrev.el.patch >From fbe88f6dd4717ae07883dfdf8e87053008293753 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Mon, 13 Nov 2023 22:24:36 +0000 Subject: [PATCH 2/2] Add 5 docstrings to abbrev.el * lisp/abbrev.el (prepare-abbrev-list-buffer) (add-abbrev) (inverse-add-abbrev) (abbrev--describe) (abbrev--possibly-save): Add docstrings. --- lisp/abbrev.el | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/lisp/abbrev.el b/lisp/abbrev.el index e1311dbc83b..70c79c1380f 100644 --- a/lisp/abbrev.el +++ b/lisp/abbrev.el @@ -122,6 +122,10 @@ abbrev-table-name found)) (defun prepare-abbrev-list-buffer (&optional local) + "Return *Abbrevs* buffer for the caller to select or display. + +LOCAL is a flag, if non-nil display only local abbrevs. +" (let ((local-table local-abbrev-table)) (with-current-buffer (get-buffer-create "*Abbrevs*") (erase-buffer) @@ -333,6 +337,22 @@ add-global-abbrev (add-abbrev global-abbrev-table "Global" arg)) (defun add-abbrev (table type arg) + "Define an abbrev in abbrev TABLE whose expansion is last word before point. +If there's an active region, use that as the expansion. + +ARG says how many words before point to use for the expansion; +zero means the entire region is the expansion. + +A negative ARG means to undefine the specified abbrev. + +TYPE of abbrev includes \"Global\", \"Mode\". + +This command reads the abbreviation from the minibuffer. + +See `add-global-abbrev', `add-mode-abbrev' for caller examples. +See `inverse-add-abbrev' for the opposite task. + +Don't use this function in a Lisp program; use `define-abbrev' instead." (let ((exp (cond ((or (and (null arg) (use-region-p)) @@ -393,6 +413,18 @@ inverse-add-global-abbrev (inverse-add-abbrev global-abbrev-table "Global" n)) (defun inverse-add-abbrev (table type arg) + "Define the word before point as as an abbrev in TABLE. + +ARG means use the ARG-th word before point as the +abbreviation. Negative ARG means use the ARG-th word after point. + +This command reads the expansion from the minibuffer, defines the +abbrev, and then expands the abbreviation in the current buffer. + +TYPE of abbrev can be \"Global\", \"Mode\". + +See `inverse-add-global-n', `inverse-add-mode-abbrev' for caller examples. +See also `add-abbrev', which performs the opposite task." (let (name exp start end) (save-excursion (forward-word (1+ (- arg))) @@ -406,7 +438,7 @@ inverse-add-abbrev nil nil nil t)) (when (or (not (abbrev-expansion name table)) (y-or-n-p (format "%s expands into \"%s\"; redefine? " - name (abbrev-expansion name table)))) + name (abbrev-expansion name table)))) (define-abbrev table (downcase name) exp) (save-excursion (goto-char end) @@ -1102,6 +1134,8 @@ abbrev--write (insert ")\n")) (defun abbrev--describe (sym) + "Describe abbrev SYM. +Used to generate a table by `insert-abbrev-table-description'." (when (symbol-value sym) (prin1 (symbol-name sym)) (if (null (abbrev-get sym :system)) @@ -1243,6 +1277,8 @@ edit-abbrevs-mode (setq font-lock-multiline nil)) (defun abbrev--possibly-save (query &optional arg) + "Hook function for use by `save-some-buffer-functions'. +Associated meaning for QUERY and ARG." ;; Query mode. (if (eq query 'query) (and save-abbrevs abbrevs-changed) -- 2.40.1 --=-=-=-- ------------=_1700209082-13524-1--