bug#41531: 27.0.91; Better handle asynchronous eldoc backends

["João Távora" <joaotavora@gmail.com>]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> "Future object."
>> +  (value 'eldoc-future--unset)
>> +  callback)
>> +
>> +(defun eldoc-future-set (f v)
>> +  "<WORLD CLASS DOCSTRING>"

Ahem.

>> +  (cl-assert (eq (eldoc-future--value f) 'eldoc-future--unset))
>> +  (setf (eldoc-future--value f) v)
>> +  (when (eldoc-future--callback f)
>> +    (funcall (eldoc-future--callback f) v)))
>> +
>> +(defun eldoc-future-set-callback (f c)
>> +  "<WORLD CLASS DOCSTRING>"

Ahem hem  :-)

>> +<WORLD CLASS DOCSTRING GOES HERE>
>
>   "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.  In this case it would be, for instance, the type of the
docstring being returns (function signature, value of a variable, etc).
The callback strategy makes it easy because there are lambda lists of
all shapes and sizes.  How does the future approach handle this?  Do
clients return structured lists of things?

> 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.  In other
situation, indeed we can be greedy.  But I don't think you can just say
to clients they dont'need to do anything.  If they returned the future
they are making _a promise_.  If they don't fullfil it something goes
wrong.

The callback case is the same, if you return non-nil non-string, you,
the eldoc function, are _required_, by Eldoc law, to call it, even if
with nil.

The equivalent in futures is just to say clients can set the value nil,
or some other application-specific indication of "sorry, I failed".

> 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.

But indeed that's only an implementation detail.  If you can make the
defined behaviour work work in some other simpler way, I have no
objections, of course.

João