bug#42222: 26.3; `called-interactively-p' doc is incorrect and misleading

[Eli Zaretskii <eliz@gnu.org>]

tags 42222 notabug
thanks

> Date: Sun, 5 Jul 2020 16:33:33 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 1. Wrong signature:
> 
>      called-interactively-p is a compiled Lisp function in 'subr.el'.
> 
>      (called-interactively-p KIND)

This is intentional, due to the 'advertised-calling-convention' form.

> 2. Nothing is said about the case where KIND is absent or nil.

See above.

>    Nothing is said about the behavior where KIND is anything other than
>    `interactive' or `any'.

We don't have to.  It means that any other value invokes undefined
behavior.

> 4. On the other hand, if the intention really is to _require_ KIND, so
>    that what the Elisp manual says is true: "KIND should be either the
>    symbol 'interactive' or the symbol 'any'", then the function should
>    raise an error when KIND is missing (and the "should" should then
>    be changed to "must").

Signaling an error is backward-incompatible, so it is not always TRT.

>      Probably introduced at or before Emacs version 22.1.
> 
>    Such meta-information should not be placed up front like that.

We clearly disagree.

There's no bug here.

Thanks.