tags 58563 + patch
quit

Stefan Monnier [2022-10-16 12:05 -0400] wrote:

>> Then my-foo's symbol-function is overwritten and its entry in
>> advertised-signature-table is no longer found, so byte-compilation no
>> longer warns about incorrect usage, and C-h f regresses to displaying:
>
> I believe this is now fixed in `master`.
>
>> C-h f also shows the expected arglist, but not for methods:
>>
>>   my-foo is a Lisp closure.
>>   (my-foo X)
>>   Frobnicate X.
>>   This is a generic function.
>>   Implementations:
>>   (my-foo X &optional _Y)
>>   Undocumented
>
> Not this, OTOH.

Do we want this fixed?

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

So the generic docstring shows the advertised signature,
and the method docstrings show the actual signature.

Whereas with a patch like that following my signature, we'd have:

  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) in ‘map.el’.
  Return non-nil if MAP contains KEY, ignoring TESTFN.
  (map-contains-key (MAP array) KEY) in ‘map.el’.
  Return non-nil if KEY is an index of MAP, ignoring TESTFN.
  (map-contains-key (MAP list) KEY) 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) in ‘map.el’.
  Undocumented

I don't know whether that's better or worse, with all the references to
the seemingly nonexistent TESTFN.  Then again, we could just update the
docstrings to mention it less.

WDYT?

P.S. There's a call to cl--generic-method-info also in elisp-mode.el.
     I wasn't sure whether the advertised signature is of use there,
     so I left it alone.

-- 
Basil