GNU bug report logs - #77124
[PATCH] Optionally display function docstring in eldoc

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 77124 in the body.
You can then email your comments to 77124 AT debbugs.gnu.org in the normal way.

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

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

From: Elijah Gabe Pérez <eg642616 <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Optionally display function docstring in eldoc
Date: Wed, 19 Mar 2025 12:32:15 -0600

[Message part 1 (text/plain, inline)]

Tags: patch

This user option tell whether 'eldoc' should display elisp function docstring.
If set to 'short' only display a short docstring, otherwise if set to
'full', display full docstring.
If set to nil do not show function docstring.

In GNU Emacs 31.0.50 (build 1, x86_64-redhat-linux-gnu, GTK+ Version
 3.24.43, cairo version 1.18.2) of 2025-03-18 built on
 0dae0d7b05b64c3db75f27d2c3f0cd33
System Description: Fedora Linux 41 (Workstation Edition)

[Message part 2 (text/html, inline)]

[0001-Optionally-display-function-docstring-in-eldoc.patch (text/patch, attachment)]

[Message part 4 (text/plain, inline)]

-- 
                                          - E.G via GNU Emacs and Org.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Elijah Gabe Pérez <eg642616 <at> gmail.com>
Cc: 77124 <at> debbugs.gnu.org
Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc
Date: Thu, 20 Mar 2025 14:25:45 +0200

> From: Elijah Gabe Pérez <eg642616 <at> gmail.com>
> Date: Wed, 19 Mar 2025 12:32:15 -0600
> 
> This user option tell whether 'eldoc' should display elisp function docstring.
> If set to 'short' only display a short docstring, otherwise if set to
> 'full', display full docstring.
> If set to nil do not show function docstring.

Where will the doc string be shown?

If in the echo-area, then what will happen when eldoc shows the info
on the mode line instead?

> +(defcustom elisp-eldoc-show-function-docstring nil
> +  "Show function docstring in `eldoc-mode'.
> +If set to `short' only display a short docstring, otherwise if set to
> +`full', display full docstring.

This should explain what is the "short docstring".  Also, where the
documentation is shown.

> +If set to nil do not show function docstring."
> +  :type '(choice
> +          (const :tag "None")
> +          (const :tag "Short" short)
> +          (const :tag "Full" full))
> +  :group 'elisp)

The :version tag is missing.

Thanks.

P.S. For the next version of the patch, please remember mentioning the
bug number in the commit log message.

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

From: Elijah Gabe Pérez <eg642616 <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 77124 <at> debbugs.gnu.org
Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc
Date: Thu, 20 Mar 2025 12:37:23 -0600

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Elijah Gabe Pérez <eg642616 <at> gmail.com>
>> Date: Wed, 19 Mar 2025 12:32:15 -0600

>> This user option tell whether 'eldoc' should display elisp function docstring.
>> If set to 'short' only display a short docstring, otherwise if set to
>> 'full', display full docstring.
>> If set to nil do not show function docstring.

> Where will the doc string be shown?

> If in the echo-area, then what will happen when eldoc shows the info
> on the mode line instead?

I've fixed it to only show in the echo-area and not to mode-line.

Also I've moved it to a function instead modifying existing ones,
similar to ~elisp-eldoc-var-docstring-with-value~.

>> +(defcustom elisp-eldoc-show-function-docstring nil
>> +  "Show function docstring in `eldoc-mode'.
>> +If set to `short' only display a short docstring, otherwise if set to
>> +`full', display full docstring.

> This should explain what is the "short docstring".  Also, where the
> documentation is shown.

I've added it.

To explain:
Instead display this full docstring:

  Set each SYM to the value of its VAL.

  The symbols SYM are variables; they are literal (not evaluated).
  The values VAL are expressions; they are evaluated.
  Thus, (setq x (1+ y)) sets x to the value of (1+ y).
  The second VAL is not computed until after the first SYM is set, and so on;
  each VAL can use the new value of variables set earlier in the setq.
  The return value of the setq form is the value of the last VAL.

Only display it like this:

  Set each SYM to the value of its VAL.

> P.S. For the next version of the patch, please remember mentioning the
> bug number in the commit log message.

Sure.

[Message part 2 (text/html, inline)]

[0001-Optionally-display-function-docstring-in-eldoc.patch (text/x-patch, attachment)]

[Message part 4 (text/plain, inline)]

-- 
                                          - E.G via GNU Emacs and Org.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Elijah Gabe Pérez <eg642616 <at> gmail.com>
Cc: 77124 <at> debbugs.gnu.org
Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc
Date: Sat, 29 Mar 2025 14:44:55 +0300

> From: Elijah Gabe Pérez <eg642616 <at> gmail.com>
> Cc: 77124 <at> debbugs.gnu.org
> Date: Thu, 20 Mar 2025 12:37:23 -0600
> 
> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -1900,6 +1900,17 @@ another pattern matching syntax that is different from that of 'pcase',
>  which some users might find less cryptic.
>  See the Info node "(elisp) cond* Macro" for details.
>  
> +---
> +** New eldoc function 'elisp-eldoc-funcall-with-docstring'.
> +This function includes the current function docstring in eldoc echo area
> +and can be used as a more detailed alternative to 'elisp-eldoc-funcall'.
> +
> +** New user option 'elisp-eldoc-funcall-with-docstring-lenght'.
> +This user option specifies how long function docstring must be displayed
> +in 'elisp-eldoc-funcall-with-docstring'.  If set to 'short' only display
> +cut docstring before period.  Otherwise if set to 'full', display full
> +docstring.'

These two entries should be moved to a separate section "ElDoc" under
"Changes in Specialized Modes and Packages in Emacs 31.1".

Also, please mark the second entry with "---", and fix a typo there
("length").

> +(defcustom elisp-eldoc-funcall-with-docstring-lenght 'short
> +  "Specify function docstring lenght in `elisp-eldoc-funcall-with-docstring'.

"Control length of doc string shown by `elisp-eldoc-funcall-with-docstring'."

(Note the typo: "length".)

> +If set to `short' only display docstring before period.,
                    ^
A comma is missing there.  Also, there's a redundant comma at the end.
And I would rephrase:

  If set to `short', only show the first sentence of the doc string.

Thanks.

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

From: Elijah Gabe Pérez <eg642616 <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 77124 <at> debbugs.gnu.org
Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc
Date: Sat, 29 Mar 2025 13:35:18 -0600

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Elijah Gabe Pérez <eg642616 <at> gmail.com>
>> Cc: 77124 <at> debbugs.gnu.org
>> Date: Thu, 20 Mar 2025 12:37:23 -0600

>> --- a/etc/NEWS
>> +++ b/etc/NEWS
>> @@ -1900,6 +1900,17 @@ another pattern matching syntax that is different from that of 'pcase',
>>  which some users might find less cryptic.
>>  See the Info node "(elisp) cond* Macro" for details.

>> +---
>> +** New eldoc function 'elisp-eldoc-funcall-with-docstring'.
>> +This function includes the current function docstring in eldoc echo area
>> +and can be used as a more detailed alternative to 'elisp-eldoc-funcall'.
>> +
>> +** New user option 'elisp-eldoc-funcall-with-docstring-lenght'.
>> +This user option specifies how long function docstring must be displayed
>> +in 'elisp-eldoc-funcall-with-docstring'.  If set to 'short' only display
>> +cut docstring before period.  Otherwise if set to 'full', display full
>> +docstring.'

> These two entries should be moved to a separate section "ElDoc" under
> "Changes in Specialized Modes and Packages in Emacs 31.1".

> Also, please mark the second entry with "---", and fix a typo there
> ("length").



>> +(defcustom elisp-eldoc-funcall-with-docstring-lenght 'short
>> +  "Specify function docstring lenght in `elisp-eldoc-funcall-with-docstring'.

> "Control length of doc string shown by `elisp-eldoc-funcall-with-docstring'."

> (Note the typo: "length".)

>> +If set to `short' only display docstring before period.,
>                     ^
> A comma is missing there.  Also, there's a redundant comma at the end.
> And I would rephrase:

>   If set to `short', only show the first sentence of the doc string.

Done.

[Message part 2 (text/html, inline)]

[0001-Optionally-display-function-docstring-in-eldoc.patch (text/x-patch, attachment)]

[Message part 4 (text/plain, inline)]

-- 
                                          - E.G via GNU Emacs and Org.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Elijah Gabe Pérez <eg642616 <at> gmail.com>
Cc: 77124-done <at> debbugs.gnu.org
Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc
Date: Sat, 05 Apr 2025 12:18:07 +0300

> From: Elijah Gabe Pérez <eg642616 <at> gmail.com>
> Cc: 77124 <at> debbugs.gnu.org
> Date: Sat, 29 Mar 2025 13:35:18 -0600
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
>  From: Elijah Gabe Pérez <eg642616 <at> gmail.com>
>  Cc: 77124 <at> debbugs.gnu.org
>  Date: Thu, 20 Mar 2025 12:37:23 -0600
> 
>  — a/etc/NEWS
>  + b/etc/NEWS
>  @@ -1900,6 +1900,17 @@ another pattern matching syntax that is different from that of 'pcase',
>  which some users might find less cryptic.
>  See the Info node "(elisp) cond* Macro" for details.
> 
>  +—
>  +** New eldoc function 'elisp-eldoc-funcall-with-docstring'.
>  +This function includes the current function docstring in eldoc echo area
>  +and can be used as a more detailed alternative to 'elisp-eldoc-funcall'.
>  +
>  +** New user option 'elisp-eldoc-funcall-with-docstring-lenght'.
>  +This user option specifies how long function docstring must be displayed
>  +in 'elisp-eldoc-funcall-with-docstring'. If set to 'short' only display
>  +cut docstring before period. Otherwise if set to 'full', display full
>  +docstring.'
> 
>  These two entries should be moved to a separate section "ElDoc" under
>  "Changes in Specialized Modes and Packages in Emacs 31.1".
> 
>  Also, please mark the second entry with "—", and fix a typo there
>  ("length").
> 
>  +(defcustom elisp-eldoc-funcall-with-docstring-lenght 'short
>  + "Specify function docstring lenght in `elisp-eldoc-funcall-with-docstring'.
> 
>  "Control length of doc string shown by `elisp-eldoc-funcall-with-docstring'."
> 
>  (Note the typo: "length".)
> 
>  +If set to `short' only display docstring before period.,
> 
>  ^
>  A comma is missing there. Also, there's a redundant comma at the end.
>  And I would rephrase:
> 
>  If set to `short', only show the first sentence of the doc string.
> 
> Done.

Thanks, installed on the master branch, and closing the bug.

Previous Next

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