Re: [elpa] externals/vertico-posframe 39dbdfe 6/7: Fix checkdoc warn.

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Maybe we should change checkdoc not to request args be mentioned?
>> Or at least not for non-interactive functions?
[...]
> I'd like to remind people why we have this convention: it's because
> some Help commands, such as apropos, only display the first line of
> the doc string.  So it's important for that line to be as informant as
> possible.

It is also used in e.g. company-mode to show documentation for
completions.  The increasingly popular marginalia package also uses
it.[1]

To me, the important question is not "does this docstring include all
arguments", but "does the first line of the docstring work by itself".

For example, if the function name is `message-with-foo-method' and the
arguments are "&rest args", I can reasonably assume that ARGS are A)
strings that B) will be shown.  But the "foo-method" part might be is
the thing that really needs explaining, and deserves all space it can
get on the first line.

IOW, as Eli points out, the checkdoc warning is one heuristic that can
help detect possible problems, but it is IMO not the end all and be all
of writing docstrings.  I think Stefan Monnier makes an important point
about that.

My idea for how to improve it would to be for checkdoc to grow some kind
of way to disable warnings for individual docstrings (with a comment
before/after ";; disable checkdoc warning #123" or similar).  Such
annotations are not uncommon in other linters.

Footnotes:
[1] I recently started using marginalia, and I really recommend everyone
     to give it a spin.  It is on GNU ELPA and works OOTB, just install
     it from GNU ELPA and say `M-x marginalia-mode'.