bug#41531: 27.0.91; Better handle asynchronous eldoc backends

[Stefan Monnier]

> --- a/lisp/emacs-lisp/eldoc.el
> +++ b/lisp/emacs-lisp/eldoc.el
> @@ -337,18 +337,32 @@ eldoc-display-message-no-interference-p
>    (not (or executing-kbd-macro (bound-and-true-p edebug-active))))
>  
>  
> +;;;; Futuristic interlude
> +(cl-defstruct (eldoc-future
> +               (:conc-name eldoc-future--)
> +               (:constructor eldoc-future-make ())) ; become Yoda we?
> +  "<WORLD CLASS DOCSTRING>"
"Future object."
> +  (value 'eldoc-future--unset)
> +  callback)
> +
> +(defun eldoc-future-set (f v)
> +  "<WORLD CLASS DOCSTRING>"
> +  (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>"
> +  (cl-assert (null (eldoc-future--callback f)))
> +  (setf (eldoc-future--callback f) c)
> +  (unless (eq (eldoc-future--value f) 'eldoc-future--unset)
> +    (funcall c (eldoc-future--value f))))
> +
> +
>  (defvar eldoc-documentation-functions nil
>    "Hook of functions that produce doc strings.
> -Each hook function should accept at least one argument CALLBACK
> -and decide whether to display a doc short string about the
> -context around point.  If the decision and the doc string can be
> -produced quickly, the hook function can ignore CALLBACK and
> -immediately return the doc string, or nil if there's no doc
> -appropriate for the context.  Otherwise, if its computation is
> -expensive or can't be performed directly, the hook function
> -should arrange for CALLBACK to be asynchronously called at a
> -later time, passing it either nil or the desired doc string.  The
> -hook function should then return a non-nil, non-string value.
> +<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.
In case the function ends up finding no information it is allowed
not to `eldoc-future-set-value` at all."

> +  (let ((x (run-hook-with-args-until-success 
> 'eldoc-documentation-functions)))
> +    (if (eldoc-future-p x) (eldoc-future-set-callback x eldoc--callback)
> +      x)))

I'd simplify this to:

    (let ((x (run-hook-with-args-until-success 'eldoc-documentation-functions)))
      (when x (eldoc-future-set-callback x eldoc--callback)))

But I'd expect that there would be no `eldoc--callback` and that it's
each `eldoc-documentation-function` which chooses its own callback
rather than being chosen by their caller.


        Stefan