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

Previous Next

Full log

View this message in rfc822 format

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Jonas Bernoulli <jonas <at> bernoul.li>
Cc: 72357 <at> debbugs.gnu.org
Subject: bug#72357: Checkdoc fixes in transient.el
Date: Sat, 14 Sep 2024 06:40:58 -0700

Jonas Bernoulli <jonas <at> bernoul.li> writes:

> 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.

Sure, I understand your reasoning.  I don't know if this needs pointing
out, but do feel free to revert these changes.

Meanwhile, Eli has proposed a rewording of the docstring that you might
want to look at.

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

Makes sense to me.

BTW, with debbugs, it's better to put people in the "X-Debbugs-CC"
header than "Cc".  That way, I get the email forwarded to me by the bug
tracker, and when I hit "wide reply", I send it to the right bug
automatically (I had to edit in manually here).

Previous Next

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