Subject: bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

From: Mathieu Marques <[email-masked]>
Date: Sat, 13 Mar 2021 13:26:56 +0100

Thanks for the feedback. Joined a replacement for 2nd patch following the
suggested improvements.

On Fri, Mar 12, 2021 at 10:13 PM Basil L. Contovounesios <[email-masked]>
wrote:

> severity 47109 wishlist
> tags 47109 patch
> quit
>
> Mathieu Marques <[email-masked]> writes:
>
> > While trying out eglot.el, I played around with eldoc.el and needed to
> > display all pieces of documentations in the echo area at once. The
> > joined patch allows for a custom separator between said
> > documentations.
>
> Thanks, CCing João as an expert on both packages.
>
> > First patch is a fix to indenting levels as well as untabifying the
> > whole file. That was done automatically by my configuration and given
> > the existing code I thought it would be beneficial to most to provide
> > a patch for that as well. Feel free to dismiss it if needed.
>
> Indeed, the Emacs convention is to only make whitespace/formatting
> changes when already modifying that code for other purposes.
>
> > Subject: [PATCH 2/2] * lisp/emacs-lisp/eldoc.el
> (eldoc--format-doc-buffer):
> >  Allow custom separator
>
> The log message should also mention the new symbols being added, e.g.:
>
>   Make ElDoc separator customizable
>
>   * lisp/emacs-lisp/eldoc.el (eldoc-documentation-separator):
>   New user option (bug#47109).
>   (eldoc-documentation-separator): New face.
>   (eldoc--format-doc-buffer): Use them as a custom separator.
>
> > +(defcustom eldoc-documentation-separator ""
> > +  "Separator to use between each documentation thing, when multiple."
> > +  :type 'string)
> > +
> > +(defface eldoc-documentation-separator '((t (:extend t :inherit
> shadow)))
>
> According to (info "(elisp) Defining Faces"), this syntax is supported
> for backward compatibility; nowadays the preferred format is:
>
>   '((t :inherit shadow :extend t))
>
> But: ElDoc supports Emacs ≥ 26.3, so use of the newer :extend attribute
> has to be conditional on that, e.g.:
>
>   `((t :inherit shadow ,@(and (>= emacs-major-version 27) '(:extend t))))
>
> > +  "Face to use for the separator between documentation things.")
>
> Both the defcustom and the defface also need a :version tag.
>
> Thanks,
>
> --
> Basil
>

-- 
Mathieu Marques
From d5a1701a75d7068d51835aab2f15153b9b989199 Mon Sep 17 00:00:00 2001
From: Mathieu Marques <[email-masked]>
Date: Fri, 12 Mar 2021 19:45:18 +0100
Subject: [PATCH] Make ElDoc separator customizable

  * lisp/emacs-lisp/eldoc.el (eldoc-documentation-separator):
  New user option (bug#47109).
  (eldoc-documentation-separator): New face.
  (eldoc--format-doc-buffer): Use them as a custom separator.
---
 lisp/emacs-lisp/eldoc.el | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 485ea26379..81fb205610 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -129,6 +129,16 @@ window.  If the value is the symbol `maybe', then the echo area
 is only skipped if the documentation doesn't fit there."
   :type 'boolean)
 
+(defcustom eldoc-documentation-separator ""
+  "Separator to use between each documentation thing, when multiple."
+  :type 'string
+  :version "28.1")
+
+(defface eldoc-documentation-separator
+  `((t :inherit shadow ,@(and (>= emacs-major-version 27) '(:extend t))))
+  "Face to use for the separator between documentation things."
+  :version "28.1")
+
 (defface eldoc-highlight-function-argument
   '((t (:inherit bold)))
   "Face used for the argument at point in a function's argument list.
@@ -490,7 +500,11 @@ This holds the results of the last documentation request."
                         ": "
                         this-doc))
                  do (insert this-doc)
-                 when rest do (insert "\n")
+                 when rest
+                 do (insert (concat
+                             "\n"
+                             (propertize eldoc-documentation-separator
+                                         'face 'eldoc-documentation-separator)))
                  finally (goto-char (point-min)))
         ;; Rename the buffer, taking into account whether it was
         ;; hidden or not
-- 
2.30.1