bug#41531: 28.0.50; proper Eldoc async support

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

[ Theodor and Fredrik, adding you since you were also interested in this
Eglot/Eldoc matter.  You can review the messages in the bug list if
you're interested:  https://debbugs.gnu.org/cgi/bugreport.cgi?bug=41531]

Andrii Kolomoiets <andreyk.mad@gmail.com> writes:

> I was planning to remove the eglot-put-doc-in-help-buffer variable in
> the near future PR as well as the use of the eglot--message function for
> the documentation display ;-)

I'm guess I'm happy to have shot these plans into the depths of the
ocean ;-)

> However, after briefly using new Eldoc and Eglot I found some issues
> that, I hope, we can fix:
>
> 1. Display only first line of the hover info.  Again :-)

You should be able to do this with either

   (setq eldoc-echo-area-use-multiline-p 1)

or

   (setq eldoc-echo-area-use-multiline-p nil)

Did you try this? If so, what exactly didn't work for you when you did?
I'm sorry if you've already given me this information in the multiple
PR's you opened about this, but let's have it again.

> 2. The hover info is sometimes displayed right before the signature info
> making the echo area to "blink".  I suppose this must be fixed on Eglot
> side by not requesting both the hover and the signature infos at the
> same time.

Not something to be fixed in Eglot, definitely, it's not its fault or
responsibility: it just reports whatever it has.  I've fixed this in
Eldoc, in the last commit.  It only affected the "eager" strategy (which
should really be called the "enthusiast" strategy).  I'll post a commit
soon using better names for strategies, I'm thinking:

eldoc-documentation-function  -> eldoc-strategy         (with obsolete alias)
eldoc-documentation-functions -> eldoc-functions        (maybe)

eldoc-documentation-default  -> eldoc-patient
eldoc-documentation-compose  -> eldoc-compose-patiently
eldoc-documentation-eager    -> eldoc-enthusiast        (Eglot uses this)
  <doesn't exist yet>        -> eldoc-compose-eagerly   (Stefan mentioned this)

> 3. That IMO useless "...truncated, see *help* buffer" message is moved
> to Eldoc.  Do we really need to show this message every time?

I see.  Maybe not _every time_ but at least _once_, I'd say.  Once per
Eldoc session (but what is an Eldoc session)?  Once per x truncated
messages?  Customization variable? (I hate those, but maybe).

Or maybe never show it?

> That one last line can be used to show additional documentation.
> Hadn't a chance to take a closer look at the code, so reporting those
> issues is the most I can do for now.

Yes, and that's fine for now, though a second pair of eyes in the code
is certainly appreciated too.

João