GNU bug report logs - #78021
30.1; Unclear sentence in (emacs)Matching

Previous Next

Full log

View this message in rfc822 format

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 78021 <at> debbugs.gnu.org
Subject: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sat, 10 May 2025 14:44:48 +0200

On Sat, 10 May 2025 13:58:44 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Stephen Berman <stephen.berman <at> gmx.net>
>> Cc: 78021 <at> debbugs.gnu.org,  drew.adams <at> oracle.com
>> Date: Thu, 08 May 2025 17:47:46 +0200
>> 
>> > I'd prefer a single patch with all the documentation changes for this
>> > mode.
>> 
>> I've now finished the patch and attached it.  On rereading my changes
>> for the Emacs manual I realized that my use of the terms "matching" and
>> "of the same type" was confusing (and confused); Drew drew attention to
>> that upthread but I misconstrued it then.  I've adjusted the text
>> accordingly (mainly in the description of
>> `electric-pair-preserve-balance') and also replaced the infelicitous
>> "unmatched" with "unpaired".  In electric-pair.el I tried to clarify and
>> improve not just the doc strings of the user options documented in the
>> manual but also a number of others that I found unclear.  I also added
>> text to the Commentary section, corrected several typos and in one case
>> reformatted overlong lines of code.
>> 
>> If you agree with these changes I'll push them to emacs-30, using the
>> ChangeLog entry below as the commit message.
>
> Thanks, LGTM, but please make sure the first line of a doc string is
> always a single complete sentence.  I've seen it be only party of a
> sentence in two functions: electric-pair-post-self-insert-function and
> electric-pair-open-newline-between-pairs-psif.

I think they are complete sentences (checkdoc did not complain about
them), though a bit terse:

  (defun electric-pair-post-self-insert-function ()
    "Do main work for `electric-pair-mode'.
  
  (defun electric-pair-open-newline-between-pairs-psif ()
    "Honor `electric-pair-open-newline-between-pairs'.

Do you prefer the following reformulations instead?

  (defun electric-pair-post-self-insert-function ()
    "Do the main work of `electric-pair-mode'.
  
  (defun electric-pair-open-newline-between-pairs-psif ()
    "Act on the value of `electric-pair-open-newline-between-pairs'.

On the other hand, checkdoc did notice something I missed (I should have
run it before posting my patch, mea culpa): that the symbol `text-mode'
in the doc string of `electric-pair--with-syntax' was not quoted, so
I've now fixed that.  In addition, checkdoc noticed that seven defuns
lack doc strings, which I had decided not to add: they are either
internal functions (electric-pair--with-syntax,
electric-pair--with-syntax-1, electric-pair--insert) or default values
of defcustoms (electric-pair-conservative-inhibit,
electric-pair-default-skip-self, electric-pair-default-inhibit), which
are adequately documented, or self-explanatory
(electric-pair-will-use-region).  Is that ok or would you rather that
these functions also have doc strings?

Steve Berman

Previous Next

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