Subject: bug#62816: 30.0.50; ElDoc blinks echo area when eldoc-documentation-compose is used

From: João Távora <[email-masked]>
Date: Thu, 13 Apr 2023 15:47:40 +0100

Hello,

Originally reported by Dmitry Gutov <[email-masked]> over
at bug#62029:

> It's trivially reproduced even with 'emacs -Q': just add somewhere
> inside an Elisp buffer:

>   (remove-hook asd)

> when flymake-mode is enabled and eldoc-documentation-strategy is
> 'eldoc-documentation-compose, and eldoc-echo-area-use-multiline-p is
> not 1, and move around 'asd' with C-f and C-b.

I've confirmed this in a graphical Emacs frame.  In a TTY frame, it's
harder or impossible to spot.  

Traced the problem down to a misimplementation of the
'eldoc-documentation-compose' strategy, which leads to potentially one
eldoc-message call to be issued for each member of
'eldoc-documentation-functions'.  In fact, with this particular
strategy, the intention at most one such call should occur (after all
the documentation items of different backends have been collected).

It's reasonably easy to fix, and I've been running the patch after my
sig all day with no problems either in Elisp or other modes.  The
"blinking" observed before is gone.

I'll push it to master soon, but leave this issue open for comments
and/or feedback a little longer.

João

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 1eb0d38c5ce..55fb518f990 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -681,29 +681,34 @@ eldoc-documentation-default
                     (lambda (f)
                       (funcall f (eldoc--make-callback :eager f)))))
 
-(defun eldoc--documentation-compose-1 (eagerlyp)
-  "Helper function for composing multiple doc strings.
-If EAGERLYP is non-nil show documentation as soon as possible,
-else wait for all doc strings."
-  (run-hook-wrapped 'eldoc-documentation-functions
-                    (lambda (f)
-                      (let* ((callback (eldoc--make-callback
-                                        (if eagerlyp :eager :patient)
-                                        f))
-                             (str (funcall f callback)))
-                        (if (or (null str) (stringp str)) (funcall callback str))
-                        nil)))
-  t)
-
 (defun eldoc-documentation-compose ()
   "Show multiple documentation strings together after waiting for all of them.
 This is meant to be used as a value for `eldoc-documentation-strategy'."
-  (eldoc--documentation-compose-1 nil))
+  (let (fns-and-callbacks)
+    ;; Make all the callbacks, this sets up state inside
+    ;; `eldoc--invoke-strategy' to know how many to wait for before
+    ;; displaying (bug#xxxxx)
+    (run-hook-wrapped 'eldoc-documentation-functions
+                      (lambda (f)
+                        (push (cons f (eldoc--make-callback :patient f))
+                              fns-and-callbacks)
+                        nil))
+    ;; Now call them.  The last one will trigger the display.
+    (cl-loop for (f . callback) in fns-and-callbacks
+             for str = (funcall f callback)
+             when (or (null str) (stringp str)) do (funcall callback str)))
+  t)
 
 (defun eldoc-documentation-compose-eagerly ()
   "Show multiple documentation strings one by one as soon as possible.
 This is meant to be used as a value for `eldoc-documentation-strategy'."
-  (eldoc--documentation-compose-1 t))
+  (run-hook-wrapped 'eldoc-documentation-functions
+                    (lambda (f)
+                      (let* ((callback (eldoc--make-callback :eager f))
+                             (str (funcall f callback)))
+                        (if (or (null str) (stringp str)) (funcall callback str))
+                        nil)))
+  t)
 
 (defun eldoc-documentation-enthusiast ()
   "Show most important documentation string produced so far.