bug#43609: 28.0.50; eldoc-documentation-function

[Dmitry Gutov <dgutov@yandex.ru>]

On 27.09.2020 11:30, martin rudalics wrote:
>  > You might want to read the docstring for
>  > eldoc-documentation-functions, in particular the part where "Each hook
>  > function is called with at least one argument CALLBACK".
> 
> That was the first thing I tried to do.  For beginners, I don't know
> what a "Hook of functions" is.  And I completely fail to understand what
> a "hook function" in this context is and when and why it gets called.

Hooks is a list of functions. They get called to fetch the doc 
information. And now there is some logic called "strategies" that 
combines the results.

> In short, I completely fail to understand the logic behind this
> variable.  All I know is that I do not want to write a hook function and
> I do not want to get called by any agent here.

No, the hook functions are written already. They are basically a list of 
functions that were previously the values of 
eldoc-documentation-function. Except it's now a list. *And* they use an 
asynchronous convention where the first argument they receive is a callback.

>  > I agree that the latest changes make Eldoc gratuitously more complex,
>  > though. You can read bug#41531, where they started.
> 
> I never read that thread (it started around a time when my mailboxes
> were thrashed due to almost simultaneous crashes of two of my mail
> receiving machines) and I subsequently had to drop a few thousands of
> mails I received earlier.  I've still not recuperated from that state.

I see. There is another email I sent to you a few months ago (about 
pop-up-mini-mode) that was also without response. I'll resend.

> I now spent more than an hour reading that thread and am as clever as
> before.  The first post in that thread seems to say everything already:
> 
>    This enables eldoc.el to exert control over how (and crucially also
>    when) to display the docstrings to the user.
> 
> In a nutshell: With eldoc-tooltip it's me and only me who decides when
> and how to display a doc string.  I do not want to leave this decision
> to a package that tries to judge whether and when that Procrustean bed
> called echo area is ready to display that doc string, whether and how to
> truncate it and when to make it disappear.  Sadly, this doesn't work any
> more in Emacs 28.  Maybe there's a simple solution to my problem but
> nobody pointed me to it so far ...

It should work if your package learns to make use of the new 
eldoc-documentation-functions hook. Or eldoc-documentation-strategy, 
which calls them.

Needless to say, I'm sure the design I advocated in the referenced 
discussion would have had better discoverability and would have been 
easier to handle in your case as well, especially regarding backward 
compatibility.

But since it has received little support, I'll leave this discussion up 
to Joao and those others who approved the current state of affairs.