GNU bug report logs - #79128
31.0.50; shortdoc doesn't always display the correct arglist

Previous Next

To reply to this bug, email your comments to 79128 AT debbugs.gnu.org.
There is no need to reopen the bug first.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 31.0.50; shortdoc doesn't always display the correct arglist
Date: Wed, 30 Jul 2025 15:26:08 +0200

emacs -Q
(require 'shortdoc)
(shortdoc 'sequence)

The entry for e.g. `seq-empty-p' says:

    (seq-empty-p arg &rest args)
      Return non-nil if the SEQUENCE is empty, nil otherwise.
      (seq-empty-p [])
        ⇒ t

But C-h f seq-empty-p says:

    seq-empty-p is a byte-code-function in ‘seq.el’.

    (seq-empty-p SEQUENCE)

    Return non-nil if the SEQUENCE is empty, nil otherwise.

      Other relevant functions are documented in the sequence group.


    This is a generic function.

    Implementations:

    (seq-empty-p (LIST list)) in ‘seq.el’.

    Optimized implementation of ‘seq-empty-p’ for lists.

    (seq-empty-p SEQUENCE) in ‘seq.el’.

    Undocumented

I imagine this is some interaction between `cl-defgeneric' with an
implementation body, `cl-defmethod', and `help-function-arglist' (other
functions in  the 'sequence group are also affected). C-h f gets it
right, but I couldnʼt find a simple function in help-fns.el to get me
the actual arglist.

Robert

In GNU Emacs 31.0.50 (build 61, x86_64-pc-linux-gnu, X toolkit, cairo
 version 1.16.0) of 2025-07-28 built on rltb
Repository revision: d895d8d06e54ec741d495d23b7cdedf978f85da8
Repository branch: master
System Description: Debian GNU/Linux 12 (bookworm)

Configured using:
 'configure --without-toolkit-scroll-bars --with-x-toolkit=lucid
 --with-xinput2 'CFLAGS=-Og -ggdb''

Message #8 received at 79128 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: 79128 <at> debbugs.gnu.org
Subject: Re: bug#79128: 31.0.50;
 shortdoc doesn't always display the correct arglist
Date: Fri, 01 Aug 2025 10:43:24 +0300

> From: Robert Pluim <rpluim <at> gmail.com>
> Date: Wed, 30 Jul 2025 15:26:08 +0200
> 
> 
> emacs -Q
> (require 'shortdoc)
> (shortdoc 'sequence)
> 
> The entry for e.g. `seq-empty-p' says:
> 
>     (seq-empty-p arg &rest args)
>       Return non-nil if the SEQUENCE is empty, nil otherwise.
>       (seq-empty-p [])
>         ⇒ t
> 
> But C-h f seq-empty-p says:
> 
>     seq-empty-p is a byte-code-function in ‘seq.el’.
> 
>     (seq-empty-p SEQUENCE)
> 
>     Return non-nil if the SEQUENCE is empty, nil otherwise.
> 
>       Other relevant functions are documented in the sequence group.
> 
> 
>     This is a generic function.
> 
>     Implementations:
> 
>     (seq-empty-p (LIST list)) in ‘seq.el’.
> 
>     Optimized implementation of ‘seq-empty-p’ for lists.
> 
>     (seq-empty-p SEQUENCE) in ‘seq.el’.
> 
>     Undocumented
> 
> I imagine this is some interaction between `cl-defgeneric' with an
> implementation body, `cl-defmethod', and `help-function-arglist' (other
> functions in  the 'sequence group are also affected). C-h f gets it
> right, but I couldnʼt find a simple function in help-fns.el to get me
> the actual arglist.

Sorry, I'm confused wrt what is the bug/issue you are reporting here.
Are you saying that shortdoc is wrong in what it says?  If so, please
elaborate why, because I see nothing wrong with what it says, given
that shortdoc is supposed to be, well, short.

Message #11 received at 79128 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79128 <at> debbugs.gnu.org
Subject: Re: bug#79128: 31.0.50; shortdoc doesn't always display the correct
 arglist
Date: Fri, 01 Aug 2025 09:56:13 +0200

>>>>> On Fri, 01 Aug 2025 10:43:24 +0300, Eli Zaretskii <eliz <at> gnu.org> said:

    Eli> Sorry, I'm confused wrt what is the bug/issue you are reporting here.
    Eli> Are you saying that shortdoc is wrong in what it says?  If so, please
    Eli> elaborate why, because I see nothing wrong with what it says, given
    Eli> that shortdoc is supposed to be, well, short.

Shortdoc:

    >> (seq-empty-p arg &rest args)

C-h f

    >> (seq-empty-p SEQUENCE)


The shortdoc implies that this is legal:

(seq-empty-p '() '())

but it gives:

Debugger entered--Lisp error: (wrong-number-of-arguments (1 . 1) 2)
  #f(compiled-function (list) "Optimized implementation of `seq-empty-p' for lists." #<bytecode -0x155616500a964cb3>)(nil nil)

Robert
-- 

Message #14 received at 79128 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Robert Pluim <rpluim <at> gmail.com>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 79128 <at> debbugs.gnu.org
Subject: Re: bug#79128: 31.0.50; shortdoc doesn't always display the correct
 arglist
Date: Sat, 02 Aug 2025 13:44:01 +0300

> From: Robert Pluim <rpluim <at> gmail.com>
> Cc: 79128 <at> debbugs.gnu.org
> Date: Fri, 01 Aug 2025 09:56:13 +0200
> 
> >>>>> On Fri, 01 Aug 2025 10:43:24 +0300, Eli Zaretskii <eliz <at> gnu.org> said:
> 
>     Eli> Sorry, I'm confused wrt what is the bug/issue you are reporting here.
>     Eli> Are you saying that shortdoc is wrong in what it says?  If so, please
>     Eli> elaborate why, because I see nothing wrong with what it says, given
>     Eli> that shortdoc is supposed to be, well, short.
> 
> Shortdoc:
> 
>     >> (seq-empty-p arg &rest args)
> 
> C-h f
> 
>     >> (seq-empty-p SEQUENCE)
> 
> 
> The shortdoc implies that this is legal:
> 
> (seq-empty-p '() '())
> 
> but it gives:
> 
> Debugger entered--Lisp error: (wrong-number-of-arguments (1 . 1) 2)
>   #f(compiled-function (list) "Optimized implementation of `seq-empty-p' for lists." #<bytecode -0x155616500a964cb3>)(nil nil)

Ah, okay.  It would be helpful to know this from the get-go.

To answer your question:

> I imagine this is some interaction between `cl-defgeneric' with an
> implementation body, `cl-defmethod', and `help-function-arglist' (other
> functions in  the 'sequence group are also affected). C-h f gets it
> right, but I couldnʼt find a simple function in help-fns.el to get me
> the actual arglist.

The function used by "C-h f" to DTRT is help-fns--signature.  AFAICT,
in this case it basically ignores what help-function-arglist returns,
and uses the car of what help-split-fundoc returns:

      (let* ((use (cond
                   ((and usage (not (listp advertised))) (car usage)) <<<<<<

At this point, I'll step aside and leave it to Stefan and others to
explain how to solve this.

Message #17 received at 79128 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79128 <at> debbugs.gnu.org, Robert Pluim <rpluim <at> gmail.com>
Subject: Re: bug#79128: 31.0.50; shortdoc doesn't always display the correct
 arglist
Date: Sat, 02 Aug 2025 15:35:44 -0400

>> Shortdoc:
>> 
>>     >> (seq-empty-p arg &rest args)

Hmm... I suggest the patch below.


        Stefan


diff --git a/lisp/help.el b/lisp/help.el
index 65950a2b3a8..d1522ee392d 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -2282,8 +2282,9 @@
   "Return a formal argument list for the function DEF.
 If PRESERVE-NAMES is non-nil, return a formal arglist that uses
 the same names as used in the original source code, when possible."
-  ;; Handle symbols aliased to other symbols.
-  (if (and (symbolp def) (fboundp def)) (setq def (indirect-function def)))
+  (let ((orig def)
+        ;; Follow symbols aliased to other symbols.
+        (def (indirect-function def)))
   ;; Advice wrappers have "catch all" args, so fetch the actual underlying
   ;; function to find the real arguments.
   (setq def (advice--cd*r def))
@@ -2299,7 +2300,10 @@
    ((or (and (byte-code-function-p def) (integerp (aref def 0)))
         (subrp def) (module-function-p def))
     (or (when preserve-names
-          (let* ((doc (condition-case nil (documentation def 'raw) (error nil)))
+            (let* ((doc (condition-case nil
+                            ;; Use `orig' to obey `function-documentation'.
+                           (documentation orig 'raw)
+                          (error nil)))
                  (docargs (if doc (car (help-split-fundoc doc nil))))
                  (arglist (if docargs
                               (cdar (read-from-string (downcase docargs)))))
@@ -2328,7 +2332,7 @@
           (nreverse arglist))))
    ((not (member (autoloadp def) '(nil keymap)))
     "[Arg list not available until function definition is loaded.]")
-   (t t)))
+     (t t))))
 
 (defun help--make-usage (function arglist)
   (cons (if (symbolp function) function 'anonymous)

Message #20 received at 79128 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 79128 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#79128: 31.0.50; shortdoc doesn't always display the correct
 arglist
Date: Mon, 04 Aug 2025 11:08:41 +0200

>>>>> On Sat, 02 Aug 2025 15:35:44 -0400, Stefan Monnier <monnier <at> iro.umontreal.ca> said:

    >>> Shortdoc:
    >>> 
    >>> >> (seq-empty-p arg &rest args)

    Stefan> Hmm... I suggest the patch below.

That fixes `seq-empty-p', but others are still sub-optimal, eg
`seq-concatenate':

    (seq-concatenate arg1 &rest rest)

which is defined as:

    (cl-defgeneric seq-concatenate (type &rest sequences)
      "Concatenate SEQUENCES into a single sequence of type TYPE.
    TYPE must be one of following symbols: `vector', `string' or `list'.

    \n(fn TYPE SEQUENCE...)"

The signature is correct, but doesnʼt obey the "(fn" thing, nor does
it preserve the argument names.

Robert
-- 

Message #23 received at 79128 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: 79128 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#79128: 31.0.50; shortdoc doesn't always display the correct
 arglist
Date: Mon, 04 Aug 2025 16:10:09 -0400

> which is defined as:
>
>     (cl-defgeneric seq-concatenate (type &rest sequences)
>       "Concatenate SEQUENCES into a single sequence of type TYPE.
>     TYPE must be one of following symbols: `vector', `string' or `list'.
>
>     \n(fn TYPE SEQUENCE...)"
>
> The signature is correct, but doesnʼt obey the "(fn" thing, nor does
> it preserve the argument names.

The (fn TYPE SEQUENCE...) syntax is not a "proper" formal arglist, so
`help-function-arglist` explicitly rejects it.  I'd just delete the
`\n(fn TYPE SEQUENCE...)` from the docstring.


        Stefan

Message #26 received at 79128 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 79128 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#79128: 31.0.50; shortdoc doesn't always display the correct
 arglist
Date: Tue, 05 Aug 2025 09:41:48 +0200

>>>>> On Mon, 04 Aug 2025 16:10:09 -0400, Stefan Monnier <monnier <at> iro.umontreal.ca> said:

    >> which is defined as:
    >> 
    >> (cl-defgeneric seq-concatenate (type &rest sequences)
    >> "Concatenate SEQUENCES into a single sequence of type TYPE.
    >> TYPE must be one of following symbols: `vector', `string' or `list'.
    >> 
    >> \n(fn TYPE SEQUENCE...)"
    >> 
    >> The signature is correct, but doesnʼt obey the "(fn" thing, nor does
    >> it preserve the argument names.

    Stefan> The (fn TYPE SEQUENCE...) syntax is not a "proper" formal arglist, so
    Stefan> `help-function-arglist` explicitly rejects it.  I'd just delete the
    Stefan> `\n(fn TYPE SEQUENCE...)` from the docstring.

That format is very common though, so I donʼt think Iʼll be wholesale
deleting those.

Your patch is good to go as far as Iʼm concerned.

Robert
-- 

Message #29 received at 79128 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: 79128 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#79128: 31.0.50; shortdoc doesn't always display the correct
 arglist
Date: Thu, 07 Aug 2025 13:50:50 -0400

>>>>>> On Sat, 02 Aug 2025 15:35:44 -0400, Stefan Monnier <monnier <at> iro.umontreal.ca> said:
>     >>> >> (seq-empty-p arg &rest args)
>     Stefan> Hmm... I suggest the patch below.
> That fixes `seq-empty-p',

Thanks, pushed to `master.


        Stefan

Message #34 received at 79128-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 79128-done <at> debbugs.gnu.org, rpluim <at> gmail.com
Subject: Re: bug#79128: 31.0.50; shortdoc doesn't always display the correct
 arglist
Date: Sat, 09 Aug 2025 15:46:29 +0300

> From: Stefan Monnier <monnier <at> iro.umontreal.ca>
> Cc: Eli Zaretskii <eliz <at> gnu.org>,  79128 <at> debbugs.gnu.org
> Date: Thu, 07 Aug 2025 13:50:50 -0400
> 
> >>>>>> On Sat, 02 Aug 2025 15:35:44 -0400, Stefan Monnier <monnier <at> iro.umontreal.ca> said:
> >     >>> >> (seq-empty-p arg &rest args)
> >     Stefan> Hmm... I suggest the patch below.
> > That fixes `seq-empty-p',
> 
> Thanks, pushed to `master.

Thanks, closing.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.