diff options
Diffstat (limited to 'lisp/emacs-lisp/eldoc.el')
| -rw-r--r-- | lisp/emacs-lisp/eldoc.el | 127 |
1 files changed, 68 insertions, 59 deletions
diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el index 6fd89a690dc..e1801c45b75 100644 --- a/lisp/emacs-lisp/eldoc.el +++ b/lisp/emacs-lisp/eldoc.el @@ -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 -proportion 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', 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 @@ -287,8 +292,10 @@ 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'." + "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 (minibufferp) (progn (add-hook 'minibuffer-exit-hook @@ -632,8 +639,8 @@ If INTERACTIVE is t, also display the buffer." (when interactive (eldoc-doc-buffer t))) (defun eldoc-documentation-default () - "Show first doc string for item at point. -Default value for `eldoc-documentation-strategy'." + "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))) @@ -651,18 +658,18 @@ else wait for all doc strings." 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)) @@ -692,40 +699,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 order as specified by the order of functions in the hook; - -- `eldoc-documentation-compose-eagerly': calls all functions in - the special hook and displays as many of the resulting doc - strings as possible, as soon as possible. Preserves 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." |