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

[Dmitry Gutov]

Hi Joao,

On 15/04/2023 12:41, João Távora wrote:
> > Perhaps the former would reuse the existing set of
> > combinator/strategies, [...]
> > This separation could still [...]
> > I'm not going to bother with a patch because backward compatibility,
> > and blah,
> Yes, I understand this, but the consequence downside is that your case
> is weakened because other brains can't see the advantages as clearly as
> your brain does.  And all brains make mistakes.  Code doesn't.
>
> > and the current approach can obviously function too, though
> > in a more complicated way.
> IMO, that can only be asserted when comparing the two things side by
> side, with actual examples.  Frequently some things are easy to do in
> one approach and harder in the competing approach, and vice versa.  In
> my brain it is your solution which_sounds_  way more complicated.  The
> key word is "sound" which I have to use because I'm hearing words inside
> my brain as I read your writing.  I'm not seeing your solution function
> in front of me, and described in non-ambiguous Elisp language with
> working examples.

This has been on my TODO for a while (sorry about the wait), so here's a 
rough patch for illustration. It incorporates an updated version of your 
earlier proposal for elisp-mode.el (from 24/03/2023) for comparison.

Some benefits that should come with it are:

1. The elements in eldoc-documentation-functions can do less work than 
the ones in eldoc-buffer-functions. I understand that this is not a 
priority for Eglot which just uses the same source of information, but 
for others it can be different. E.g. require an extra network call to 
fetch the full docstring (this is not a hypothetical).
2. Different eldoc-documentation-strategy can be used for the buffer's 
contents. E.g. using the current one (first non-nil) for the echo and 
the "compose" for the buffer seems logical to me, and the patch 
illustrates it.
3. 'M-x eldoc-doc-buffer' is made synchronous and only shows info for 
the point, not a result of some earlier lookup, which might (or might 
not) get refreshed asynchronously.

There can be other solutions for 1 (e.g. passing some extra info *into* 
each eldoc-documentation-functions, so they can choose what to show, 
rather than have them provide all variations in the returned value), but 
it seems harder to find one for 2.

Drawbacks:
1. Seemingly more duplication in the code (but other doc providers might 
choose to use entirely different looks; no duplication in that case).
2. When both functions are based off the same info, reusing it gets 
harder. But it's nothing a extra cache cannot fix.

eldoc-doc-buffer.diff
Description: Text Data