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

From: "Basil L. Contovounesios" <[email-masked]>
Date: Fri, 12 Mar 2021 21:13:51 +0000

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