bug#41531: 27.0.91; Better handle asynchronous eldoc backends

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

Eli Zaretskii <eliz@gnu.org> writes:

>> -(defun eldoc-message (&optional string)
>> +(make-obsolete
>> + 'eldoc-message "use `eldoc-documentation-functions' instead." "1.1.0")
>
> Isn't the version part of the obsolete message supposed to tell the
> version of Emacs?

Stuck with "1.1.0", because of the GNU ELPA criterion.  But maybe the
string could be "1.1.0-elpa" or something like that.

> The change to the number of arguments of the functions in the
> eldoc-documentation-functions hook is backward-incompatible, isn't it?
> I see you've changed the relevant functions in our sources, but what
> about 3rd-party packages?

Answered this already.

> Also, the doc string of this hook needs clarification regarding the
> arguments: it first says that CALLBACK is the only mandatory argument
> to the hook functions, but then, out of the blue, appear additional
> arguments DOCSTRING and a list of key-value pairs.  Confusing.

Changed that paragraph to

   To call the CALLBACK function, the hook function must pass it an
   obligatory argument DOCSTRING, a string containing the
   documentation, followed by an optional list of keyword-value
   pairs of the form (:KEY VALUE :KEY2 VALUE2...).  KEY can be:

The situation is very similar to Flymake's flymake-diagnostic-functions.
If you still find this docstring confusing, maybe I should copy that
docstring's structure.

> The doc strings have some words in UK English spelling "(e.g.,
> "honour"), please fix that.  Also, please make sure comments all start
> with a capital letter, end with a period, and comprise full English
> sentences.

I fixed all I could find, but is this a a hard rule?  I like to break it
once in a while:

    ;; We have to foo bar separately ...
    (foo bar)
    ;; ... because the bazness might be too quuxy.
    (if (quux) (foo baz))

I ended up not doing that this time, though.

> The doc string of eldoc-documentation-compose doesn't say a word about
> the function's argument.

I fixed that by creating a helper eldoc--documentation-compose-1 that
both eldoc-documentation-compose and eldoc-documentation-compose-eagerly
call.  I describe the arg in the helper.

> This doc string doesn't explain the use of the timer, it explains the
> reason for its existence.  It should also describe the use:

See the new version below.  I think it is sufficient.  Be aware this is
an internal variable, we don't even let the user customize the time (we
could though, but I think it's overcomplicating, for now).

    (defvar eldoc--enthusiasm-curbing-timer nil
      "Timer used by the `eldoc-documentation-enthusiast' strategy.
    When a doc string is encountered, it must endure a certain amount
    of time unchallenged until it is displayed to the user.  This
    prevents blinking if a lower priority docstring comes in shortly
    before a higher priority one.")

> Last, but not least: the "async" part of the branch's name hints on
> some advanced and extremely useful functionality that these changes
> are supposed to allow, but I see no mention of that in NEWS and in the
> manual bits.  What did I miss?

I reworded it, caught a bug, and mentioned
eldoc-echo-area-use-multiline-p.  Let me know it if you're missing
anything.

João

PS: Actually a proper section for Eldoc in the Emacs manual is probably
missing, but I don't have time to work on it straight away.  Or at least
I think the fix should go in first.