bug#72357: Checkdoc fixes in transient.el

[Stefan Kangas <stefankangas@gmail.com>]

Jonas Bernoulli <jonas@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).