GNU bug report logs - #72357
Checkdoc fixes in transient.el

Previous Next

Full log

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jonas Bernoulli <jonas <at> bernoul.li>
To: Stefan Kangas <stefankangas <at> gmail.com>, bug-gnu-emacs <at> gnu.org
Subject: Checkdoc fixes in transient.el
Date: Mon, 29 Jul 2024 23:56:00 +0200

Hello Stefan,

I don't think your commit e3bba63ecb9 is an improvement.

I generally agree that the first line of a docstring should be a short
sentence, and that no other sentence should start on that line, even if
there is plenty of space left.  In fact I have contributed many similar
fixes to package maintained by other people.

However, I would argue that the usual reasoning for why one should do
that, does not apply here.  In this case, the first line won't appear
anywhere by itself, without the rest of this docstring (such as in
apropos output), because this is a method not a "regular" or generic
function.

Looking at, for example, "C-h f transient-format-description", I feel
that it would not make sense if all the methods themselves began with a
summary line.  Only the overall generic function *needs* a summary line.
In some case it may make sense to give individual methods their own
summary lines, but for very short, one paragraph method docstrings this
should not be a requirements.  When a method is so simple that it can be
described using a single short paragraph (but not a single sentence,
which can fit on a single line), then that should be possible, without
being forced to mess up the justification of that paragraph.

IMO checkdoc should be updated to not enforce the conventions, which
were designed for "top-level" functions (and variables) on methods
as well.

Also consider the case where a method can be described using a single
sentence, but that sentence requires two lines.  Forcing the author
to prefix that short paragraph with a sorter sentence, which only
serves to satisfies an ill-applied convention, feels wrong to me.

---

In this particular case, separating the first sentence from the rest of
the paragraph (but without completely rewording the paragraph) is a step
backward.

Each of these method docstrings consist of two sentences.  The first
sentence is very much not a summary of the second sentence.  Each of
these methods does two things and each thing is described using one
sentence.  The important thing, the one that makes the method useful, is
described in the second sentence.  The boring thing (call the next
method) is described in the first sentence, because it is done first.
Using the first sentence as the "summary" is wrong in these cases.
Changing the order in which the two steps are described, would likely
lead to awkward wording.

     Jonas

Previous Next

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