ElDoc: remember origin backend in doc snippets (bug#62029)

This lays groundwork for discriminating between different
documentation providers in ElDoc display outlets, i.e. members
of eldoc-display-functions

* lisp/emacs-lisp/eldoc.el (eldoc--make-callback): Take extra origin arg.
(eldoc-documentation-compose-1)
(eldoc-documentation-compose-eagerly)
(eldoc-documentation-default): Pass extra arg to eglot--make-callback.
(eldoc--invoke-strategy): Rework.
(eldoc-documentation-functions): Work docstring.

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 74bef264bf1a6155cf29613600b5281322c858e9..8fc109dcfefbad798c6935813eedafeddb1a02db 100644 (file)
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -448,6 +448,11 @@ documentation-displaying frontends.  For example, KEY can be:
   `eldoc-display-in-echo-area' and `eldoc-display-in-buffer' will
   use when displaying `:thing''s value.
 
+* `:origin', VALUE being the member of
+  `eldoc-documentation-functions' where DOCSTRING
+  originated. `eldoc-display-in-buffer' may use this organize the
+  documentation buffer accordingly.
+
 Finally, major modes should modify this hook locally, for
 example:
   (add-hook \\='eldoc-documentation-functions #\\='foo-mode-eldoc nil t)
@@ -644,8 +649,9 @@ If INTERACTIVE is t, also display the buffer."
 (defun eldoc-documentation-default ()
   "Show the first non-nil documentation string for item at point.
 This is the default value for `eldoc-documentation-strategy'."
-  (run-hook-with-args-until-success 'eldoc-documentation-functions
-                                    (eldoc--make-callback :patient)))
+  (run-hook-wrapped 'eldoc-documentation-functions
+                    (lambda (f)
+                      (funcall f (eldoc--make-callback :eager f)))))
 
 (defun eldoc--documentation-compose-1 (eagerlyp)
   "Helper function for composing multiple doc strings.
@@ -654,7 +660,8 @@ else wait for all doc strings."
   (run-hook-wrapped 'eldoc-documentation-functions
                     (lambda (f)
                       (let* ((callback (eldoc--make-callback
-                                        (if eagerlyp :eager :patient)))
+                                        (if eagerlyp :eager :patient)
+                                        f))
                              (str (funcall f callback)))
                         (if (or (null str) (stringp str)) (funcall callback str))
                         nil)))
@@ -675,7 +682,7 @@ This is meant to be used as a value for `eldoc-documentation-strategy'."
 This is meant to be used as a value for `eldoc-documentation-strategy'."
   (run-hook-wrapped 'eldoc-documentation-functions
                     (lambda (f)
-                      (let* ((callback (eldoc--make-callback :enthusiast))
+                      (let* ((callback (eldoc--make-callback :enthusiast f))
                              (str (funcall f callback)))
                         (if (stringp str) (funcall callback str))
                         nil)))
@@ -780,7 +787,7 @@ before a higher priority one.")
 ;; `eldoc--invoke-strategy' could be moved to
 ;; `eldoc-documentation-strategy' or thereabouts if/when we decide to
 ;; extend or publish the `make-callback' protocol.
-(defun eldoc--make-callback (method)
+(defun eldoc--make-callback (method origin)
   "Make callback suitable for `eldoc-documentation-functions'.
 The return value is a function FN whose lambda list is (STRING
 &rest PLIST) and can be called by those functions.  Its
@@ -800,8 +807,11 @@ have the following values:
    `eldoc-documentation-functions' have been collected;
 
 - `:eager' says to display STRING along with all other competing
-  strings so far, as soon as possible."
-  (funcall eldoc--make-callback method))
+  strings so far, as soon as possible.
+
+ORIGIN is the member of `eldoc-documentation-functions' which
+will be responsible for eventually calling the FN."
+  (funcall eldoc--make-callback method origin))
 
 (defun eldoc--invoke-strategy (interactive)
   "Invoke `eldoc-documentation-strategy' function.
@@ -838,9 +848,10 @@ the docstrings eventually produced, using
          (docs-registered '()))
     (cl-labels
         ((register-doc
-          (pos string plist)
+          (pos string plist origin)
           (when (and string (> (length string) 0))
-            (push (cons pos (cons string plist)) docs-registered)))
+            (push (cons pos (cons string `(:origin ,origin ,@plist)))
+                  docs-registered)))
          (display-doc
           ()
           (run-hook-with-args
@@ -850,7 +861,7 @@ the docstrings eventually produced, using
                                                         (lambda (a b) (< (car a) (car b))))))
            interactive))
          (make-callback
-          (method)
+          (method origin)
           (let ((pos (prog1 howmany (cl-incf howmany))))
             (cl-ecase method
               (:enthusiast
@@ -858,7 +869,7 @@ the docstrings eventually produced, using
                  (when (and string (cl-loop for (p) in docs-registered
                                             never (< p pos)))
                    (setq docs-registered '())
-                   (register-doc pos string plist))
+                   (register-doc pos string plist origin))
                  (when (and (timerp eldoc--enthusiasm-curbing-timer)
                             (memq eldoc--enthusiasm-curbing-timer
                                   timer-list))
@@ -870,12 +881,12 @@ the docstrings eventually produced, using
               (:patient
                (cl-incf want)
                (lambda (string &rest plist)
-                 (register-doc pos string plist)
+                 (register-doc pos string plist origin)
                  (when (zerop (cl-decf want)) (display-doc))
                  t))
               (:eager
                (lambda (string &rest plist)
-                 (register-doc pos string plist)
+                 (register-doc pos string plist origin)
                  (display-doc)
                  t))))))
       (let* ((eldoc--make-callback #'make-callback)