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

[Stefan Monnier]

Eli Zaretskii [2021-10-29 09:29:15] wrote:
>> 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.

To be honest, I'm not sure either.  I do find most that the warning
about args not mentioned in the docstring to be by far the one that
creates the largest number of "false positives" (in most cases, they're
actually not false in he sense that indeed the args aren't mentioned,
but their lack is not a serious problem).

IME, this warning corresponds to a WIBNI rather than a FIXME.

It's the main reason why I never try to reach "0 warnings" from checkdoc.

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

Hmm... AFAIK this warning is unrelated to the first line or the 80
columns conventions.  It just says things like:

    Argument ‘prompt’ should appear (as PROMPT) in the doc string

> (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 know I'm perfect, but actually I do find this (usually annoying)
warning occasionally useful, to prod me into completing a doc string.

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

I think you're talking about a different convention than the one I'm
talking about (and the patch I quoted fixes the one I'm talking about
but doesn't touche the first line of the docstring).


        Stefan