Subject: bug#77124: closed (Re: bug#77124: [PATCH] Optionally display function docstring in eldoc)

From: [email-masked] (GNU bug Tracking System)
Date: Sat, 05 Apr 2025 09:19:02 +0000

Your bug report

#77124: [PATCH] Optionally display function docstring in eldoc

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
77124: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=77124
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc
From: Eli Zaretskii <[email-masked]>
To: Elijah Gabe Pérez <[email-masked]>
Cc: [email-masked]
Date: Sat, 05 Apr 2025 12:18:07 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Elijah Gabe Pérez <[email-masked]>
> Cc: [email-masked]
> Date: Sat, 29 Mar 2025 13:35:18 -0600
> 
> Eli Zaretskii <[email-masked]> writes:
> 
>  From: Elijah Gabe Pérez <[email-masked]>
>  Cc: [email-masked]
>  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.

Subject: [PATCH] Optionally display function docstring in eldoc
From: Elijah Gabe Pérez <[email-masked]>
To: [email-masked]
Date: Wed, 19 Mar 2025 12:32:15 -0600
List-Id: <debbugs-submit.debbugs.gnu.org>

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)

>From 1b97cd0dff054c862e81434f1376109bb9d30c66 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?El=C3=ADas=20Gabriel=20P=C3=A9rez?= <[email-masked]>
Date: Wed, 19 Mar 2025 12:01:22 -0600
Subject: [PATCH] Optionally display function docstring in eldoc

Allow display (optionally) function docstring in eldoc.
* etc/NEWS: Announce changes.
* lisp/progmodes/elisp-mode.el (elisp-eldoc-var-docstring-with-value):
New user option.
(elisp-get-fnsym-args-string): Display function docstring.
---
 etc/NEWS                     |  7 +++++++
 lisp/progmodes/elisp-mode.el | 24 ++++++++++++++++++++++--
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 0797fc03217..b0a0e6cb6a3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1900,6 +1900,13 @@ 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 user option 'elisp-eldoc-show-function-docstring'.
+This user option tell whether 'eldoc' should display 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.
+
 ---
 ** New function 'shell-command-do-open'.
 This lets a Lisp program access the core functionality of the
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index a34f29bffea..761d392be63 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -1882,6 +1882,17 @@ elisp-eldoc-var-docstring-with-value
 				   (format "[%sc more]" more)))))
 	       :thing cs
 	       :face 'font-lock-variable-name-face))))
+(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.
+
+If set to nil do not show function docstring."
+  :type '(choice
+          (const :tag "None")
+          (const :tag "Short" short)
+          (const :tag "Full" full))
+  :group 'elisp)
 
 (defun elisp-get-fnsym-args-string (sym &optional index)
   "Return a string containing the parameter list of the function SYM.
@@ -1908,8 +1919,17 @@ elisp-get-fnsym-args-string
 		     (substitute-command-keys (car doc)))
 		    (t (help-function-arglist sym)))))
              ;; Stringify, and store before highlighting, downcasing, etc.
-	     (elisp--last-data-store sym (elisp-function-argstring args)
-                                     'function))))))
+	     (elisp--last-data-store
+              sym
+              (concat (elisp-function-argstring args)
+                      (pcase elisp-eldoc-show-function-docstring
+                        ('full
+                         (concat "\n" (cdr doc)))
+                        ('short
+                         (save-match-data
+                           (when (string-match "\\." (cdr doc))
+                             (concat "\n" (substring (cdr doc) 0 (match-end 0))))))))
+              'function))))))
     ;; Highlight
     (if argstring
 	(elisp--highlight-function-argument
-- 
2.48.1

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