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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Feng Shu <tumashu@163.com>
> Date: Thu, 28 Oct 2021 23:07:37 -0400
> 
> In my experience checkdoc's warning about arguments not mentioned in the
> docstring aren't very helpful (it's quite common that the arguments
> aren't mentioned.  Here for example, it's the same args as those of
> `minibuffer-message`, so there's no strong need to repeat the doc here.
> Also the function could come without docstring in which case
> checkdoc wouldn't complain about that missing arg doc).
> 
> Maybe we should change checkdoc not to request args be mentioned?
> Or at least not for non-interactive functions?

I'm not sure such a change will be for the better.  Many times people
don't reference the arguments there because they are unaware of our
style conventions, or because they cannot find the wording which would
mention the arguments and still stay within the 80-char limitation.
IME, it's a constant source of patch review comments, and having
checkdoc look at this is useful.  (I understand that none of the above
is the case for code that you, Stefan, write, but you are one of the
few exceptions in this regard.)

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.