bug#41531: 27.0.91; Better handle asynchronous eldoc backends

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

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

>>> You mean a single call could return first a function signature and
>>> a while later a docstring?
>> No, that's not what I mean.  Those should be two different members of
>> eldoc-documentation-functions (plural).
> Great.

Indeed, I can see 3 eldoc sources for emacs-lisp mode, in this order:

- function signature
- docstring
- special variable value

If emacs-lisp-mode one uses the default display strategy
(eldoc-documentation-default or some rename of that) and sets
eldoc-echo-area-use-multiline-p to 1, it should be fully backward
compatible to the current behaviour.

Alternatively, we can have emacs-lisp-mode keep out of
eldoc-echo-area-use-multiline-p and use 4 sources:

- function signature
- one-line docstring
- special variable value
- remaining paragraphs of docstring

( At some point, if we compose all of these bits of information in the
volatile *eldoc* buffer, it will start looking a lot like *Help* for C-h
o, There's some integration work to do there, but I'd rather not open
that can of worms just now. )

>>>> 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.
>> Yes, I agree, but it's IMO easier to read (funcall cb :foo 42 :baz 23)
>> than (set-value fut (list :foo 42 :baz 23)).
>
> I find the difference largely irrelevant.  Much more important is
> what kinds of :foo and bar are allowed and what they do.

I agree.  Content is more important than style.  Of course style
matters, too.  Occasionally, it matters overwhelmingly.  But not
here. I'd say.  The promises-vs-callbacks discussion is a matter of
style.

>> In fact, a much better name for eldoc-documentation-function (singular)
>> is eldoc-documentation-strategy, not least because it relieves us from
>> this silly singular/plural confusion.
>
> Sounds very good.  Changing its name will make it possible to fix the
> current backward-incompatibility (which we'd fix by re-introducing a(n
> obsolete) eldoc-documentation-function).

Yes, that's the plan.

João