From 9b18407c7fd91313544acfb3457be5447987e20a Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Wed, 22 Mar 2023 13:35:43 +0000 Subject: [PATCH] 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. --- lisp/emacs-lisp/eldoc.el | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el index 74bef264bf1..8fc109dcfef 100644 --- 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) -- 2.39.2