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

From: Elijah Gabe Pérez <[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.

>From 2644e590277c6d3f38b2bc3b3da42526ee256475 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. (Bug#77124)
* etc/NEWS: Document changes.
* lisp/progmodes/elisp-mode.el
(elisp-eldoc-funcall-with-docstring-length): New user option.
(elisp-eldoc-funcall-with-docstring): New function.
---
 etc/NEWS                     | 13 +++++++++++
 lisp/progmodes/elisp-mode.el | 44 ++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/etc/NEWS b/etc/NEWS
index cc63d03eafe..16934dfb21b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -534,6 +534,19 @@ The prompts 'opstring' and 'active-opstring' can now either be strings
 or functions.  This is useful when your prompts can benefit from dynamic
 content.
 
+** ElDoc
+---
+*** 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-length'.
+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.'
+
 ---
 ** Buffer Menu
 
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index a34f29bffea..748d2f11360 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -1845,6 +1845,50 @@ elisp-eldoc-funcall
                          'font-lock-function-name-face
                        'font-lock-keyword-face)))))
 
+(defcustom elisp-eldoc-funcall-with-docstring-length 'short
+  "Control length of doc string shown by `elisp-eldoc-funcall-with-docstring'.
+If set to `short', only show the first sentence of the doc string.
+Otherwise if set to `full', display full doc string."
+  :type '(choice
+          (const :tag "Short" short)
+          (const :tag "Full" full))
+  :group 'elisp
+  :version "31.1")
+
+(defun elisp-eldoc-funcall-with-docstring (callback &rest _ignored)
+  "Document function call at point by calling CALLBACK.
+Intended for `eldoc-documentation-functions' (which see).
+Compared to `elisp-eldoc-funcall', this also includes the
+current function doc string, doc string length depends on
+`elisp-eldoc-funcall-with-docstring-length'."
+  (let* ((sym-info (elisp--fnsym-in-current-sexp))
+         (fn-sym (car sym-info))
+         (doc (when (fboundp fn-sym)
+                (propertize
+                 (cdr (help-split-fundoc
+                       (condition-case nil (documentation fn-sym t)
+                         (invalid-function nil))
+                       fn-sym))
+                 'face 'font-lock-doc-face))))
+    (when fn-sym
+      (funcall callback
+               (concat (apply #'elisp-get-fnsym-args-string sym-info)
+                       ;; Ensure not display the docstring in the
+                       ;; mode-line.
+                       (when (and doc (not (minibufferp)))
+                         (concat
+                          "\n"
+                          (pcase elisp-eldoc-funcall-with-docstring-length
+                            ('full doc)
+                            ('short
+                             (save-match-data
+                               (when (string-match "\\." doc)
+                                 (concat "\n" (substring doc 0 (match-end 0))))))))))
+               :thing fn-sym
+               :face (if (functionp fn-sym)
+                         'font-lock-function-name-face
+                       'font-lock-keyword-face)))))
+
 (defun elisp-eldoc-var-docstring (callback &rest _ignored)
   "Document variable at point by calling CALLBACK.
 Intended for `eldoc-documentation-functions' (which see).
-- 
2.49.0

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