Subject: bug#78021: 30.1; Unclear sentence in (emacs)Matching

From: Stephen Berman <[email-masked]>
Date: Sat, 10 May 2025 14:44:48 +0200

On Sat, 10 May 2025 13:58:44 +0300 Eli Zaretskii <[email-masked]> wrote:

>> From: Stephen Berman <[email-masked]>
>> Cc: [email-masked],  [email-masked]
>> 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