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

From: Elijah Gabe Pérez <[email-masked]>
Date: Wed, 19 Mar 2025 12:32:15 -0600

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.