Subject: Re: bug#62029: 29.0.60; Allow users to customize eldoc buffer separator

From: João Távora <[email-masked]>
Date: Fri, 24 Mar 2023 17:44:10 +0000

Yuan Fu <[email-masked]> writes:

> For separator, maybe something like
>
> (insert “Title" (propertize "-" 'display
>                             '(space :align-to right)
>                             'font-lock-face '(:strike-through t)
>                             'face '(:strike-through t)))
>
> for GUI, and use underline for terminal.

I've now pushed a commit to master introducing the user variable
eldoc-doc-buffer-separator.  It's not a defcustom yet, as I'm not too
familiar with those, but feel free to change it.

  (defvar eldoc-doc-buffer-separator
    "String used to separate items in Eldoc documentation buffer."
    (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend t)) "\n"))

There is a difference between a separator and a title.  I've stopped
short of adding titles, as I fear it would be confusing unless the
content allows it.  To be investigated later for
eldoc-display-in-echo-area or maybe you can try it in eldoc-box.

Also, I've been testing with these unpushed changes to elisp-mode.el,
which render more of the docstring in emacs-lisp-mode.

The use case here is navigating around in an .el file while having a
window open with the *eldoc* buffer.

João

diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index 45e3848362e..054da900616 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -1779,11 +1779,22 @@ 'elisp-eldoc-documentation-function
 
 (defun elisp-eldoc-funcall (callback &rest _ignored)
   "Document function call at point by calling CALLBACK.
-Intended for `eldoc-documentation-functions' (which see)."
+Intended for `eldoc-documentatiok-functions' (which see)."
   (let* ((sym-info (elisp--fnsym-in-current-sexp))
-         (fn-sym (car sym-info)))
+         (fn-sym (car sym-info))
+         (echo (and fn-sym
+                    (apply #'elisp-get-fnsym-args-string sym-info)))
+         (fulldoc
+          (and echo
+               (with-temp-buffer
+                 (let ((standard-output (current-buffer)))
+                   (describe-function-1 fn-sym)
+                   (help-make-xrefs)
+                   (buffer-string))))))
     (when fn-sym
-      (funcall callback (apply #'elisp-get-fnsym-args-string sym-info)
+      (funcall callback
+               fulldoc
+               :echo echo
                :thing fn-sym
                :face (if (functionp fn-sym)
                          'font-lock-function-name-face
@@ -1794,9 +1805,18 @@ elisp-eldoc-var-docstring
 Intended for `eldoc-documentation-functions' (which see).
 Also see `elisp-eldoc-var-docstring-with-value'."
   (let* ((sym (elisp--current-symbol))
-         (docstring (and sym (elisp-get-var-docstring sym))))
+         (docstring (and sym (elisp-get-var-docstring sym)))
+         (rawdoc (and docstring
+                      (documentation-property
+                       sym 'variable-documentation t)))
+         (fulldoc (and rawdoc
+                       (with-temp-buffer
+                         (insert rawdoc)
+                         (help-make-xrefs)
+                         (buffer-string)))))
     (when docstring
-      (funcall callback docstring
+      (funcall callback fulldoc
+               :echo docstring
                :thing sym
                :face 'font-lock-variable-name-face))))