bug#41531: 27.0.91; Better handle asynchronous eldoc backends

[Stefan Monnier]

>>> +  "<WORLD CLASS DOCSTRING>"
> Ahem.
>>> +  "<WORLD CLASS DOCSTRING>"
> Ahem hem  :-)

Not sure what you mean ;-)

>>   "Special hook run to get the documentation string at point.
>> Each function is called with no argument and should return either nil
>> or an `eldoc-future` object that should have its `value` set as soon
>> as possible via `eldoc-future-set-value` (it can be set before
>> returning the future or at a later time).
>> This value should be a string, typically occupying only a single line.
> Sometimes clients want to return more than one value, i.e. set more than
> one value.

You mean a single call could return first a function signature and
a while later a docstring?  Or at the same time.
If at the same time, then it should return them combined into a single
value (concatenation of strings, list, you name it).

The infrastructure so far only accepts strings as far as I know, so
until that is changed the question seems moot.

> The callback strategy makes it easy because there are lambda lists of
> all shapes and sizes.

It's trivial to use a list to bring the number back down to 1, so it's
not much of a difference.

> How does the future approach handle this?
> Do clients return structured lists of things?

If we want to extend it that way, that would be the natural thing to do,
I guess.  Tho without knowing what the different elements represent
(i.e. some kind of semantic information about that list), I'm not sure
what the callback can do with it other than presume that all elements
are strings and concatenate them.

>> In case the function ends up finding no information it is allowed
>> not to `eldoc-future-set-value` at all."
> This is problematic.  In the eldoc-documentation-compose situation we
> need to wait for every backend to reply before composing.

We definitely don't want to wait: if a backend responds quickly we
should show that info immediately, and update the info if/when another
backend gives additional info.

OTOH indeed for the non-composing situation, we'd need to know that the
1st backend finished unsuccessfully before being able to use the
second backend.  So I guess you're right: we shouldn't allow backends to
drop requests :-(

>> each `eldoc-documentation-function` which chooses its own callback
>> rather than being chosen by their caller.
> For this to work, i.e. to be able to handle multiple responses, I think
> it has to be set by their caller, i.e. eldoc-print-current-symbol-info:
> that's the central "hub" that maintains information about how many
> backends have responded and how many haven't.

I don't think this structure can work well: the "hub" needs to work
differently for compose than for "return first".


        Stefan