master 8fc18d0968a 1/2: Optionally display function docstring in eldoc

[Eli Zaretskii]

branch: master
commit 8fc18d0968a0f7ef610b6868a35e731c778991ac
Author: Elías Gabriel Pérez <eg642616@gmail.com>
Commit: Eli Zaretskii <eliz@gnu.org>

    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 5ee1e3596dd..caef5080422 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -565,6 +565,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 @@ Intended for `eldoc-documentation-functions' (which 
see)."
                          '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).