bug#58563: 29.0.50; Generic functions and advertised-calling-convention

[Stefan Monnier]

>> Not this, OTOH.
> Do we want this fixed?

Maybe.

> Currently C-h f map-contains-key RET says:
>
>   map-contains-key is a byte-compiled Lisp function in ‘map.el’.
>   (map-contains-key MAP KEY)
>   Return non-nil if and only if MAP contains KEY.
>   TESTFN is deprecated.  Its default depends on MAP.
>   The default implementation delegates to ‘map-some’.
>     Probably introduced at or before Emacs version 27.1.
>   This is a generic function.
>   Implementations:
>   (map-contains-key (MAP hash-table) KEY &optional TESTFN) in ‘map.el’.
>   Return non-nil if MAP contains KEY, ignoring TESTFN.
>   (map-contains-key (MAP array) KEY &optional TESTFN) in ‘map.el’.
>   Return non-nil if KEY is an index of MAP, ignoring TESTFN.
>   (map-contains-key (MAP list) KEY &optional TESTFN) in ‘map.el’.
>   Return non-nil if MAP contains KEY.
>   If MAP is an alist, TESTFN defaults to ‘equal’.
>   If MAP is a plist, TESTFN defaults to ‘eq’.
>   (map-contains-key MAP KEY &optional TESTFN) in ‘map.el’.
>   Undocumented

The current code also allows things like a (A B Rest C) in the
defgeneric and then more precise args in the methods,

> I don't know whether that's better or worse, with all the references to
> the seemingly nonexistent TESTFN.

Exactly.  It's not clear what's "right", so I think it's better to err
on the safer(?) side and apply the `advertised-calling-convention` to
the place where it's set.

`advertised-calling-convention` is not used very often (and that's
good), so I don't think it's super important to do the very best we can
with it.  We currently cover byte-compiler warnings when too many args
are passed, the arglist in Eldoc, and the top-line arglist in `C-h f`.
I think it's pretty good already.


        Stefan