From 287ca04e77a5e68d3af97d5229bb23d4717ef6f6 Mon Sep 17 00:00:00 2001 From: Andreas Gerler Date: Sat, 25 Nov 2023 11:28:41 +0100 Subject: [PATCH] update eldoc Signed-off-by: Andreas Gerler --- elpa/eldoc-1.11.0.signed | 1 - elpa/eldoc-1.11.0/eldoc-pkg.el | 2 - elpa/eldoc-1.14.0.signed | 1 + .../eldoc-autoloads.el | 41 +- elpa/eldoc-1.14.0/eldoc-pkg.el | 2 + elpa/{eldoc-1.11.0 => eldoc-1.14.0}/eldoc.el | 380 +++++++++++------- 6 files changed, 261 insertions(+), 166 deletions(-) delete mode 100644 elpa/eldoc-1.11.0.signed delete mode 100644 elpa/eldoc-1.11.0/eldoc-pkg.el create mode 100644 elpa/eldoc-1.14.0.signed rename elpa/{eldoc-1.11.0 => eldoc-1.14.0}/eldoc-autoloads.el (60%) create mode 100644 elpa/eldoc-1.14.0/eldoc-pkg.el rename elpa/{eldoc-1.11.0 => eldoc-1.14.0}/eldoc.el (74%) diff --git a/elpa/eldoc-1.11.0.signed b/elpa/eldoc-1.11.0.signed deleted file mode 100644 index c6a30fce..00000000 --- a/elpa/eldoc-1.11.0.signed +++ /dev/null @@ -1 +0,0 @@ -Good signature from 066DAFCB81E42C40 GNU ELPA Signing Agent (2019) (trust undefined) created at 2020-10-24T23:05:01+0200 using RSA \ No newline at end of file diff --git a/elpa/eldoc-1.11.0/eldoc-pkg.el b/elpa/eldoc-1.11.0/eldoc-pkg.el deleted file mode 100644 index 74f5764b..00000000 --- a/elpa/eldoc-1.11.0/eldoc-pkg.el +++ /dev/null @@ -1,2 +0,0 @@ -;;; Generated package description from eldoc.el -*- no-byte-compile: t -*- -(define-package "eldoc" "1.11.0" "Show function arglist or variable docstring in echo area" '((emacs "26.3")) :url "http://elpa.gnu.org/packages/eldoc.html" :keywords '("extensions") :authors '(("Noah Friedman" . "friedman@splode.com")) :maintainer '("Noah Friedman" . "friedman@splode.com")) diff --git a/elpa/eldoc-1.14.0.signed b/elpa/eldoc-1.14.0.signed new file mode 100644 index 00000000..161a4079 --- /dev/null +++ b/elpa/eldoc-1.14.0.signed @@ -0,0 +1 @@ +Good signature from 066DAFCB81E42C40 GNU ELPA Signing Agent (2019) (trust undefined) created at 2023-04-03T11:05:02+0200 using RSA \ No newline at end of file diff --git a/elpa/eldoc-1.11.0/eldoc-autoloads.el b/elpa/eldoc-1.14.0/eldoc-autoloads.el similarity index 60% rename from elpa/eldoc-1.11.0/eldoc-autoloads.el rename to elpa/eldoc-1.14.0/eldoc-autoloads.el index c484ed40..51131f88 100644 --- a/elpa/eldoc-1.11.0/eldoc-autoloads.el +++ b/elpa/eldoc-1.14.0/eldoc-autoloads.el @@ -1,4 +1,4 @@ -;;; eldoc-autoloads.el --- automatically extracted autoloads +;;; eldoc-autoloads.el --- automatically extracted autoloads -*- lexical-binding: t -*- ;; ;;; Code: @@ -17,10 +17,19 @@ String to display in mode line when ElDoc Mode is enabled; nil for none.") (autoload 'eldoc-mode "eldoc" "\ Toggle echo area display of Lisp objects at point (ElDoc mode). -If called interactively, enable Eldoc mode if ARG is positive, -and disable it if ARG is zero or negative. If called from Lisp, -also enable the mode if ARG is omitted or nil, and toggle it if -ARG is `toggle'; disable the mode otherwise. +This is a minor mode. If called interactively, toggle the `Eldoc +mode' mode. If the prefix argument is positive, enable the mode, +and if it is zero or negative, disable the mode. + +If called from Lisp, toggle the mode if ARG is `toggle'. Enable +the mode if ARG is nil, omitted, or is a positive number. +Disable the mode if ARG is a negative number. + +To check whether the minor mode is enabled in the current buffer, +evaluate `eldoc-mode'. + +The mode's hook is called both when the mode is enabled and when +it is disabled. ElDoc mode is a buffer-local minor mode. When enabled, the echo area displays information about a function or variable in the @@ -33,24 +42,28 @@ expression point is on. (put 'global-eldoc-mode 'globalized-minor-mode t) -(defvar global-eldoc-mode t "\ +(defcustom global-eldoc-mode t "\ Non-nil if Global Eldoc mode is enabled. See the `global-eldoc-mode' command for a description of this minor mode. Setting this variable directly does not take effect; either customize it (see the info node `Easy Customization') -or call the function `global-eldoc-mode'.") +or call the function `global-eldoc-mode'." :set #'custom-set-minor-mode :initialize 'custom-initialize-delay :type 'boolean) (custom-autoload 'global-eldoc-mode "eldoc" nil) (autoload 'global-eldoc-mode "eldoc" "\ Toggle Eldoc mode in all buffers. With prefix ARG, enable Global Eldoc mode if ARG is positive; -otherwise, disable it. If called from Lisp, enable the mode if -ARG is omitted or nil. +otherwise, disable it. + +If called from Lisp, toggle the mode if ARG is `toggle'. +Enable the mode if ARG is nil, omitted, or is a positive number. +Disable the mode if ARG is a negative number. + +Eldoc mode is enabled in all buffers where `turn-on-eldoc-mode' would +do it. -Eldoc mode is enabled in all buffers where -`turn-on-eldoc-mode' would do it. See `eldoc-mode' for more information on Eldoc mode. \(fn &optional ARG)" t nil) @@ -59,7 +72,11 @@ See `eldoc-mode' for more information on Eldoc mode. Turn on `eldoc-mode' if the buffer has ElDoc support enabled. See `eldoc-documentation-strategy' for more detail." nil nil) -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "eldoc" '("eldoc"))) +(register-definition-prefixes "eldoc" '("eldoc")) + +;;;*** + +;;;### (autoloads nil nil ("eldoc-pkg.el") (0 0 0 0)) ;;;*** diff --git a/elpa/eldoc-1.14.0/eldoc-pkg.el b/elpa/eldoc-1.14.0/eldoc-pkg.el new file mode 100644 index 00000000..efc83608 --- /dev/null +++ b/elpa/eldoc-1.14.0/eldoc-pkg.el @@ -0,0 +1,2 @@ +;; Generated package description from eldoc.el -*- no-byte-compile: t -*- +(define-package "eldoc" "1.14.0" "Show function arglist or variable docstring in echo area" '((emacs "26.3")) :commit "f2357df91f0262949618bd4da571d3267c1b1dfa" :url "https://elpa.gnu.org/packages/eldoc.html" :authors '(("Noah Friedman" . "friedman@splode.com")) :maintainer '("Noah Friedman" . "friedman@splode.com") :keywords '("extensions")) diff --git a/elpa/eldoc-1.11.0/eldoc.el b/elpa/eldoc-1.14.0/eldoc.el similarity index 74% rename from elpa/eldoc-1.11.0/eldoc.el rename to elpa/eldoc-1.14.0/eldoc.el index 9d77cbb7..1eb0d38c 100644 --- a/elpa/eldoc-1.11.0/eldoc.el +++ b/elpa/eldoc-1.14.0/eldoc.el @@ -1,11 +1,11 @@ ;;; eldoc.el --- Show function arglist or variable docstring in echo area -*- lexical-binding:t; -*- -;; Copyright (C) 1996-2020 Free Software Foundation, Inc. +;; Copyright (C) 1996-2023 Free Software Foundation, Inc. ;; Author: Noah Friedman ;; Keywords: extensions ;; Created: 1995-10-06 -;; Version: 1.11.0 +;; Version: 1.14.0 ;; Package-Requires: ((emacs "26.3")) ;; This is a GNU ELPA :core package. Avoid functionality that is not @@ -55,21 +55,24 @@ :group 'extensions) (defcustom eldoc-idle-delay 0.50 - "Number of seconds of idle time to wait before printing. + "Number of seconds of idle time to wait before displaying documentation. If user input arrives before this interval of time has elapsed after the -last input, no documentation will be printed. +last input event, no documentation will be displayed. -If this variable is set to 0, no idle time is required." +If this variable is set to 0, display the documentation without any delay." :type 'number) (defcustom eldoc-print-after-edit nil - "If non-nil eldoc info is only shown when editing. + "If non-nil, eldoc info is only shown after editing commands. Changing the value requires toggling `eldoc-mode'." :type 'boolean) (defcustom eldoc-echo-area-display-truncation-message t "If non-nil, provide verbose help when a message has been truncated. -If nil, truncated messages will just have \"...\" appended." +When this is non-nil, and the documentation string was truncated to +fit in the echo-area, the documentation will be followed by an +explanation of how to display the full documentation text. +If nil, truncated messages will just have \"...\" to indicate truncation." :type 'boolean :version "28.1") @@ -93,22 +96,24 @@ Note that this variable has no effect, unless (defcustom eldoc-echo-area-use-multiline-p 'truncate-sym-name-if-fit "Allow long ElDoc doc strings to resize echo area display. -If value is t, never attempt to truncate messages, even if the -echo area must be resized to fit. +If the value is t, never attempt to truncate messages, even if the +echo area must be resized to fit. In that case, Emacs will resize +the mini-window up to the limit set by `max-mini-window-height'. If the value is a positive number, it is used to calculate a -number of logical lines of documentation that ElDoc is allowed to -put in the echo area. If a positive integer, the number is used -directly, while a float specifies the number of lines as a -proporting of the echo area frame's height. +number of screen lines of documentation that ElDoc is allowed to +put in the echo area. A positive integer specifies the maximum +number of lines directly, while a floating-point number specifies +the number of screen lines as a fraction of the echo area frame's +height. -If value is the symbol `truncate-sym-name-if-fit' t, the part of +If the value is the symbol `truncate-sym-name-if-fit', the part of the doc string that represents a symbol's name may be truncated if it will enable the rest of the doc string to fit on a single line, without resizing the echo area. -If value is nil, a doc string is always truncated to fit in a -single line of display in the echo area. +If the value is nil, a doc string is always truncated to fit in a +single screen line of echo-area display. Any resizing of the echo area additionally respects `max-mini-window-height'." @@ -121,12 +126,12 @@ Any resizing of the echo area additionally respects line" truncate-sym-name-if-fit))) (defcustom eldoc-echo-area-prefer-doc-buffer nil - "Prefer ElDoc's documentation buffer if it is showing in some frame. + "Prefer ElDoc's documentation buffer if it is displayed in some window. If this variable's value is t, ElDoc will skip showing documentation in the echo area if the dedicated documentation -buffer (given by `eldoc-doc-buffer') is being displayed in some -window. If the value is the symbol `maybe', then the echo area -is only skipped if the documentation doesn't fit there." +buffer (displayed by `eldoc-doc-buffer') is already displayed in +some window. If the value is the symbol `maybe', then the echo area +is only skipped if the documentation needs to be truncated there." :type 'boolean) (defface eldoc-highlight-function-argument @@ -241,13 +246,15 @@ expression point is on." :lighter eldoc-minor-mode-string ;; `emacs-lisp-mode' itself? (cond ((<= emacs-major-version 27) (declare-function elisp-eldoc-documentation-function "elisp-mode") - (add-function :before-until (local 'eldoc-documentation-function) - #'elisp-eldoc-documentation-function)) + (with-no-warnings + (add-function :before-until (local 'eldoc-documentation-function) + #'elisp-eldoc-documentation-function))) (t (add-hook 'eldoc-documentation-functions #'elisp-eldoc-var-docstring nil t) (add-hook 'eldoc-documentation-functions #'elisp-eldoc-funcall nil t) - (setq eldoc-documentation-strategy 'eldoc-documentation-default))) + (setq-local eldoc-documentation-strategy + 'eldoc-documentation-default))) (eldoc-mode +1)) ;;;###autoload @@ -285,15 +292,13 @@ reflect the change." (put 'eldoc-mode-line-string 'risky-local-variable t) (defun eldoc-minibuffer-message (format-string &rest args) - "Display messages in the mode-line when in the minibuffer. -Otherwise work like `message'." - (if (minibufferp) + "Display message specified by FORMAT-STRING and ARGS on the mode-line as needed. +This function displays the message produced by formatting ARGS +with FORMAT-STRING on the mode line when the current buffer is a minibuffer. +Otherwise, it displays the message like `message' would." + (if (or (bound-and-true-p edebug-mode) (minibufferp)) (progn - (add-hook 'minibuffer-exit-hook - (lambda () (setq eldoc-mode-line-string nil - ;; https://debbugs.gnu.org/16920 - eldoc-last-message nil)) - nil t) + (add-hook 'post-command-hook #'eldoc-minibuffer--cleanup) (with-current-buffer (window-buffer (or (window-in-direction 'above (minibuffer-window)) @@ -312,6 +317,13 @@ Otherwise work like `message'." (force-mode-line-update))) (apply #'message format-string args))) +(defun eldoc-minibuffer--cleanup () + (unless (or (bound-and-true-p edebug-mode) (minibufferp)) + (setq eldoc-mode-line-string nil + ;; https://debbugs.gnu.org/16920 + eldoc-last-message nil) + (remove-hook 'post-command-hook #'eldoc-minibuffer--cleanup))) + (make-obsolete 'eldoc-message "use `eldoc-documentation-functions' instead." "eldoc-1.1.0") (defun eldoc-message (&optional string) (eldoc--message string)) @@ -378,7 +390,18 @@ Also store it in `eldoc-last-message' and return that value." ;; it undesirable to print eldoc messages right this instant. (defun eldoc-display-message-no-interference-p () "Return nil if displaying a message would cause interference." - (not (or executing-kbd-macro (bound-and-true-p edebug-active)))) + (not (or executing-kbd-macro + ;; The following configuration shows "Matches..." in the + ;; echo area when point is after a closing bracket, which + ;; conflicts with eldoc. + (and (boundp 'show-paren-context-when-offscreen) + show-paren-context-when-offscreen + ;; There's no conflict with the child-frame and + ;; overlay versions. + (not (memq show-paren-context-when-offscreen + '(child-frame overlay))) + (not (pos-visible-in-window-p + (overlay-end show-paren--overlay))))))) (defvar eldoc-documentation-functions nil @@ -389,12 +412,12 @@ name, inside its arg list, or on any object with some associated information. Each hook function is called with at least one argument CALLBACK, -a function, and decides whether to display a doc short string +a function, and decides whether to display a short doc string about the context around point. - If that decision can be taken quickly, the hook function may - call CALLBACK immediately following the protocol described - below. Alternatively it may ignore CALLBACK entirely and + call CALLBACK immediately, following the protocol described + below. Alternatively, it may ignore CALLBACK entirely and return either the doc string, or nil if there's no doc appropriate for the context. @@ -414,7 +437,7 @@ documentation-producing backend to cooperate with specific documentation-displaying frontends. For example, KEY can be: * `:thing', VALUE being a short string or symbol designating what - is being reported on. It can, for example be the name of the + DOCSTRING reports on. It can, for example be the name of the function whose signature is being documented, or the name of the variable whose docstring is being documented. `eldoc-display-in-echo-area', a member of @@ -425,6 +448,17 @@ 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. +* `:echo', controlling how `eldoc-display-in-echo-area' should + present this documentation item in the echo area, to save + space. If VALUE is a string, echo it instead of DOCSTRING. If + a number, only echo DOCSTRING up to that character position. + If `skip', don't echo DOCSTRING at all. + +The additional KEY `:origin' is always added by ElDoc, its VALUE +being the member of `eldoc-documentation-functions' where +DOCSTRING originated. `eldoc-display-functions' may use this +information to organize display of multiple docstrings. + Finally, major modes should modify this hook locally, for example: (add-hook \\='eldoc-documentation-functions #\\='foo-mode-eldoc nil t) @@ -435,7 +469,7 @@ return any documentation.") (defvar eldoc-display-functions '(eldoc-display-in-echo-area eldoc-display-in-buffer) "Hook of functions tasked with displaying ElDoc results. -Each function is passed two arguments: DOCS and INTERACTIVE. DOCS +Each function is passed two arguments: DOCS and INTERACTIVE. DOCS is a list (DOC ...) where DOC looks like (STRING :KEY VALUE :KEY2 VALUE2 ...). STRING is a string containing the documentation's text and the remainder of DOC is an optional list of @@ -448,50 +482,87 @@ directly from the user or from ElDoc's automatic mechanisms'.") (defvar eldoc--doc-buffer nil "Buffer displaying latest ElDoc-produced docs.") -(defvar eldoc--doc-buffer-docs nil "Documentation items in `eldoc--doc-buffer'.") - (defun eldoc-doc-buffer (&optional interactive) + "Get or display ElDoc documentation buffer. + +The buffer holds the results of the last documentation request. +If INTERACTIVE, display it. Else, return said buffer." (interactive (list t)) - "Display ElDoc documentation buffer. -This holds the results of the last documentation request." (unless (buffer-live-p eldoc--doc-buffer) - (setq eldoc--doc-buffer (get-buffer-create "*eldoc*"))) - (when interactive - (display-buffer eldoc--doc-buffer))) + (user-error (format + "ElDoc buffer doesn't exist, maybe `%s' to produce one." + (substitute-command-keys "\\[eldoc]")))) + (with-current-buffer eldoc--doc-buffer + (cond (interactive + (rename-buffer (replace-regexp-in-string "^ *" "" + (buffer-name))) + (display-buffer (current-buffer))) + (t (current-buffer))))) + +(defvar eldoc-doc-buffer-separator + (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend t)) "\n") + "String used to separate items in Eldoc documentation buffer.") (defun eldoc--format-doc-buffer (docs) "Ensure DOCS are displayed in an *eldoc* buffer." - (interactive (list t)) - (eldoc-doc-buffer) ;; ensure buffer exists - (with-current-buffer eldoc--doc-buffer - (unless (eq docs eldoc--doc-buffer-docs) - (setq-local eldoc--doc-buffer-docs docs) - (let ((inhibit-read-only t) - (things-reported-on)) - (erase-buffer) (setq buffer-read-only t) - (local-set-key "q" 'quit-window) - (cl-loop for (docs . rest) on docs - for (this-doc . plist) = docs - for thing = (plist-get plist :thing) - when thing do - (cl-pushnew thing things-reported-on) - (setq this-doc - (concat - (propertize (format "%s" thing) - 'face (plist-get plist :face)) - ": " - this-doc)) - do (insert this-doc) - when rest do (insert "\n")) - ;; Maybe rename the buffer. - (rename-buffer (if things-reported-on - (format "*eldoc for %s*" - (mapconcat (lambda (s) (format "%s" s)) - things-reported-on - ", ")) - "*eldoc*"))))) + (with-current-buffer (if (buffer-live-p eldoc--doc-buffer) + eldoc--doc-buffer + (setq eldoc--doc-buffer + (get-buffer-create " *eldoc*"))) + (let ((inhibit-read-only t) + (things-reported-on)) + (special-mode) + (erase-buffer) + (setq-local nobreak-char-display nil) + (cl-loop for (docs . rest) on docs + for (this-doc . plist) = docs + for thing = (plist-get plist :thing) + when thing do + (cl-pushnew thing things-reported-on) + (setq this-doc + (concat + (propertize (format "%s" thing) + 'face (plist-get plist :face)) + ": " + this-doc)) + do (insert this-doc) + when rest do + (insert eldoc-doc-buffer-separator) + finally (goto-char (point-min))) + ;; Rename the buffer, taking into account whether it was + ;; hidden or not + (rename-buffer (format "%s*eldoc%s*" + (if (string-match "^ " (buffer-name)) " " "") + (if things-reported-on + (format " for %s" + (mapconcat + (lambda (s) (format "%s" s)) + things-reported-on + ", ")) + ""))))) eldoc--doc-buffer) +(defun eldoc--echo-area-render (docs) + "Similar to `eldoc--format-doc-buffer', but for echo area. +Helper for `eldoc-display-in-echo-area'." + (cl-loop for (item . rest) on docs + for (this-doc . plist) = item + for echo = (plist-get plist :echo) + for thing = (plist-get plist :thing) + unless (eq echo 'skip) do + (setq this-doc + (cond ((integerp echo) (substring this-doc 0 echo)) + ((stringp echo) echo) + (t this-doc))) + (when thing (setq this-doc + (concat + (propertize (format "%s" thing) + 'face (plist-get plist :face)) + ": " + this-doc))) + (insert this-doc) + (when rest (insert "\n")))) + (defun eldoc--echo-area-substring (available) "Given AVAILABLE lines, get buffer substring to display in echo area. Helper for `eldoc-display-in-echo-area'." @@ -499,7 +570,8 @@ Helper for `eldoc-display-in-echo-area'." (goto-char (point-min)) (skip-chars-forward " \t\n") (point)) - (goto-char (line-end-position available)) + (forward-visible-line (1- available)) + (end-of-visible-line) (skip-chars-backward " \t\n"))) (truncated (save-excursion (skip-chars-forward " \t\n") @@ -509,7 +581,8 @@ Helper for `eldoc-display-in-echo-area'." ((and truncated (> available 1) eldoc-echo-area-display-truncation-message) - (goto-char (line-end-position 0)) + (forward-visible-line -1) + (end-of-visible-line) (concat (buffer-substring start (point)) (format "\n(Documentation truncated. Use `%s' to see rest)" @@ -520,19 +593,20 @@ Helper for `eldoc-display-in-echo-area'." (defun eldoc--echo-area-prefer-doc-buffer-p (truncatedp) "Tell if display in the echo area should be skipped. Helper for `eldoc-display-in-echo-area'. If TRUNCATEDP the -documentation to potentially appear in the echo are is truncated." +documentation to potentially appear in the echo area is +known to be truncated." (and (or (eq eldoc-echo-area-prefer-doc-buffer t) (and truncatedp (eq eldoc-echo-area-prefer-doc-buffer 'maybe))) - (get-buffer-window eldoc--doc-buffer))) + (get-buffer-window eldoc--doc-buffer t))) (defun eldoc-display-in-echo-area (docs _interactive) "Display DOCS in echo area. Honor `eldoc-echo-area-use-multiline-p' and `eldoc-echo-area-prefer-doc-buffer'." (cond - (;; Check if he wave permission to mess with echo area at all. For + (;; Check if we have permission to mess with echo area at all. For ;; example, if this-command is non-nil while running via an idle ;; timer, we're still in the middle of executing a command, e.g. a ;; query-replace where it would be annoying to overwrite the echo @@ -574,16 +648,18 @@ Honor `eldoc-echo-area-use-multiline-p' and single-doc) ((and (numberp available) (cl-plusp available)) - ;; Else, given a positive number of logical lines, we - ;; format the *eldoc* buffer, using as most of its - ;; contents as we know will fit. - (with-current-buffer (eldoc--format-doc-buffer docs) + ;; Else, given a positive number of logical lines, grab + ;; as many as we can. + (with-temp-buffer + (eldoc--echo-area-render docs) (eldoc--echo-area-substring available))) (t ;; this is the "truncate brutally" situation (let ((string - (with-current-buffer (eldoc--format-doc-buffer docs) + (with-temp-buffer + (eldoc--echo-area-render docs) (buffer-substring (goto-char (point-min)) - (line-end-position 1))))) + (progn (end-of-visible-line) + (point)))))) (if (> (length string) width) ; truncation to happen (unless (eldoc--echo-area-prefer-doc-buffer-p t) (truncate-string-to-width string width)) @@ -595,15 +671,15 @@ Honor `eldoc-echo-area-use-multiline-p' and (defun eldoc-display-in-buffer (docs interactive) "Display DOCS in a dedicated buffer. If INTERACTIVE is t, also display the buffer." - (let ((buf (eldoc--format-doc-buffer docs))) - (when interactive - (display-buffer buf)))) + (eldoc--format-doc-buffer docs) + (when interactive (eldoc-doc-buffer t))) (defun eldoc-documentation-default () - "Show first doc string for item at point. -Default value for `eldoc-documentation-strategy'." - (run-hook-with-args-until-success 'eldoc-documentation-functions - (eldoc--make-callback :patient))) + "Show the first non-nil documentation string for item at point. +This is the default value for `eldoc-documentation-strategy'." + (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. @@ -612,28 +688,29 @@ 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))) t) (defun eldoc-documentation-compose () - "Show multiple doc strings at once after waiting for all. -Meant as a value for `eldoc-documentation-strategy'." + "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)) (defun eldoc-documentation-compose-eagerly () - "Show multiple doc strings at once as soon as possible. -Meant as a value for `eldoc-documentation-strategy'." + "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)) (defun eldoc-documentation-enthusiast () - "Show most important doc string produced so far. -Meant as a value for `eldoc-documentation-strategy'." + "Show most important documentation string produced so far. +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))) @@ -660,40 +737,42 @@ Meant as a value for `eldoc-documentation-strategy'." (eldoc--documentation-strategy-defcustom eldoc-documentation-strategy eldoc-documentation-function #'eldoc-documentation-default - "How to collect and organize results of `eldoc-documentation-functions'. - -This variable controls how `eldoc-documentation-functions', which -specifies the sources of documentation, is queried and how its -results are organized before being displayed to the user. The -following values are allowed: - -- `eldoc-documentation-default': calls functions in the special - hook in order until one is found that produces a doc string - value. Display only that value; - -- `eldoc-documentation-compose': calls all functions in the - special hook and displays all of the resulting doc strings - together. Wait for all strings to be ready, and preserve their - relative as specified by the order of functions in the hook; - -- `eldoc-documentation-compose-eagerly': calls all functions in - the special hook and display as many of the resulting doc - strings as possible, as soon as possibl. Preserving the - relative order of doc strings; - -- `eldoc-documentation-enthusiast': calls all functions in the - special hook and displays only the most important resulting - docstring one at any given time. A function appearing first in - the special hook is considered more important. - -This variable can also be set to a function of no args that -returns something other than a string or nil and allows for some + "How to collect and display results of `eldoc-documentation-functions'. + +This variable controls how to call the functions in the special hook +`eldoc-documentation-functions', and how to organize their results +for display to the user. The functions in `eldoc-documentation-functions' +are the source of documentation, and act as back-end for ElDoc. + +The following values are supported: + +- `eldoc-documentation-default': Call functions in the special + hook in order, until one of them returns a non-nil string + value. Display only that string. + +- `eldoc-documentation-compose': Call all the functions in the + special hook and display all of the resulting strings together, + after all of the functions were called, and in the order of the + functions in the hook. + +- `eldoc-documentation-compose-eagerly': Call all the functions in + the special hook, and display each non-nil string as soon as it + is returned by a function, before calling the next function. + +- `eldoc-documentation-enthusiast': Call all the functions in the + special hook, and display only the most important resulting + string at any given time. A function appearing first in + the special hook is considered more important than those which + appear after it. + +This variable can also be set to a function of no arguments that +returns something other than a string or nil, and allows for some or all of the special hook `eldoc-documentation-functions' to be run. In that case, the strategy function should follow that -other variable's protocol closely and endeavor to display the -resulting doc strings itself. +other variable's protocol closely and display the resulting doc +strings itself. -For backward compatibility to the \"old\" protocol, this variable +For backward compatibility with the \"old\" protocol, this variable can also be set to a function that returns nil or a doc string, depending whether or not there is documentation to display at all." @@ -736,7 +815,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 @@ -756,8 +835,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. @@ -779,7 +861,7 @@ function passes responsibility to the functions in Other third-party values of `eldoc-documentation-strategy' should not use `eldoc--make-callback'. They must find some alternate way to produce callbacks to feed to -`eldoc-documentation-function' and should endeavour to display +`eldoc-documentation-functions' and should endeavor to display the docstrings eventually produced, using `eldoc-display-functions'." (let* (;; How many callbacks have been created by the strategy @@ -794,9 +876,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 @@ -806,7 +889,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 @@ -814,7 +897,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)) @@ -826,19 +909,22 @@ 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) (res (funcall eldoc-documentation-strategy))) ;; Observe the old and the new protocol: - (cond (;; Old protocol: got string, output immediately; - (stringp res) (register-doc 0 res nil) (display-doc)) + (cond (;; Old protocol: got string, e-d-strategy is iself the + ;; origin function, and we output immediately; + (stringp res) + (register-doc 0 res nil eldoc-documentation-strategy) + (display-doc)) (;; Old protocol: got nil, clear the echo area; (null res) (eldoc--message nil)) (;; New protocol: trust callback will be called; @@ -854,11 +940,7 @@ the docstrings eventually produced, using eldoc--last-request-state)) (let ((non-essential t)) (setq eldoc--last-request-state token) - ;; Only keep looking for the info as long as the user hasn't - ;; requested our attention. This also locally disables - ;; inhibit-quit. - (while-no-input - (eldoc--invoke-strategy nil))))))) + (eldoc--invoke-strategy nil)))))) ;; This section only affects ElDoc output to the echo area, as in @@ -906,10 +988,6 @@ the docstrings eventually produced, using "previous-" "recenter" "right-" "scroll-" "self-insert-command" "split-window-" "up-list") -;;;; ChangeLog: - - - (provide 'eldoc) ;;; eldoc.el ends here -- 2.47.3