From 8ce2b89aa138815344b579adf5781d830e18dad0 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 21 Oct 2022 16:10:08 +0300 Subject: [PATCH] Improve and extend documentation of ElDoc * lisp/emacs-lisp/eldoc.el (eldoc-documentation-strategy) (eldoc-documentation-enthusiast) (eldoc-documentation-compose-eagerly) (eldoc-documentation-compose, eldoc-documentation-default) (eldoc-minibuffer-message, eldoc-idle-delay) (eldoc-print-after-edit) (eldoc-echo-area-display-truncation-message) (eldoc-echo-area-use-multiline-p) (eldoc-echo-area-prefer-doc-buffer): Doc string fixes. * doc/emacs/emacs.texi (Top): * doc/emacs/programs.texi (Documentation, Programming Language Doc): Rename "Lisp Doc" to "Programming Language Doc", including in parent menus. All references changed. (Programming Language Doc): Formerly "Lisp Doc". Rewrite to not be specific to Emacs Lisp. Improve markup and wording. Document more commands and variables. * doc/emacs/maintaining.texi (Maintaining): Improve indexing. --- doc/emacs/custom.texi | 2 +- doc/emacs/emacs.texi | 2 +- doc/emacs/maintaining.texi | 2 + doc/emacs/modes.texi | 2 +- doc/emacs/programs.texi | 147 ++++++++++++++++++++++++++++--------- doc/lispref/symbols.texi | 6 +- doc/misc/octave-mode.texi | 7 +- doc/misc/sem-user.texi | 2 +- lisp/emacs-lisp/eldoc.el | 127 +++++++++++++++++--------------- 9 files changed, 194 insertions(+), 103 deletions(-) diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 6e5a0ddc1c7..08ada2a70bb 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1271,7 +1271,7 @@ mode: my-new disable a minor mode in a local variables list, use the @code{eval} keyword with a Lisp expression that runs the mode command (@pxref{Minor Modes}). For example, the following local variables -list enables ElDoc mode (@pxref{Lisp Doc}) by calling +list enables ElDoc mode (@pxref{Programming Language Doc}) by calling @code{eldoc-mode} with no argument (calling it with an argument of 1 would do the same), and disables Font Lock mode (@pxref{Font Lock}) by calling @code{font-lock-mode} with an argument of @minus{}1. diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 727f5f93bff..5c81641bf63 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -718,7 +718,7 @@ Documentation Lookup * Info Lookup:: Looking up library functions and commands in Info files. * Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. +* Programming Language Doc:: Looking up program functions, variables, etc. C and Related Modes diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 94171b3a089..2de6b3604f8 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -4,6 +4,8 @@ @c See file emacs.texi for copying conditions. @node Maintaining @chapter Maintaining Large Programs +@cindex maintaining large programs +@cindex large programming projects, maintaining This chapter describes Emacs features for maintaining medium- to large-size programs and packages. These features include: diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi index 56b779f8de6..1a32f619478 100644 --- a/doc/emacs/modes.texi +++ b/doc/emacs/modes.texi @@ -127,7 +127,7 @@ see which mode is actually being entered. Modes}). For example, you can put the following lines in your init file to enable Flyspell minor mode in all text-based major modes (@pxref{Spelling}), and ElDoc minor mode in Emacs Lisp mode -(@pxref{Lisp Doc}): +(@pxref{Programming Language Doc}): @example (add-hook 'text-mode-hook 'flyspell-mode) diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index b5e577d96a4..3c08909d418 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1197,7 +1197,7 @@ use in your program. @menu * Info Lookup:: Looking up library functions and commands in Info files. * Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. +* Programming Language Doc:: Looking up program functions, variables, etc. @end menu @node Info Lookup @@ -1298,8 +1298,10 @@ WoMan Manual}. the WoMan Info manual, which is distributed with Emacs. @end ifnotinfo -@node Lisp Doc -@subsection Emacs Lisp Documentation Lookup +@node Programming Language Doc +@subsection Programming Language Documentation Lookup +@cindex documentation for program symbols +@cindex program functions and variables, documentation lookup When editing Emacs Lisp code, you can use the commands @kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) @@ -1307,43 +1309,120 @@ to view the built-in documentation for the Lisp functions and variables that you want to use. @xref{Name Help}. @cindex ElDoc mode +@cindex at-point documentation for program symbols @findex eldoc-mode @findex global-eldoc-mode - ElDoc is a buffer-local minor mode that helps with looking up Lisp -documentation. When it is enabled, the echo area displays some useful -information whenever there is a Lisp function or variable at point; -for a function, it shows the argument list, and for a variable it -shows the first line of the variable's documentation string. To -toggle ElDoc mode, type @kbd{M-x eldoc-mode}. There's also a Global -ElDoc mode, which is turned on by default, and affects buffers whose -major mode sets the variables described below. Use @w{@kbd{M-x -global-eldoc-mode}} to turn it off globally. - -@vindex eldoc-documentation-strategy -@vindex eldoc-documentation-functions - These variables can be used to configure ElDoc mode: + ElDoc@footnote{ +The name ``ElDoc'' is a historical accident: this mode started by +supporting Emacs Lisp buffers. +} is a buffer-local minor mode that helps with looking up +documentation of symbols (functions, methods, classes, variables, +etc.) in your program. When this mode is enabled, the echo area +displays useful information whenever there is a documented symbol at +point. For example, in buffers under the Emacs Lisp mode, it shows +the argument list of a function at point, and for a Lisp variable it +shows the first line of the variable's documentation string. + +To toggle ElDoc mode, type @kbd{M-x eldoc-mode}. There's also a +Global ElDoc mode, which is turned on by default, and turns on the +ElDoc mode in buffers whose major mode sets the variables described +below. Use @w{@kbd{M-x global-eldoc-mode}} to turn it off globally. + +Various major modes configure the Global ElDoc mode to use their +documentation functions. Examples include Emacs Lisp mode, Python +mode, and Cfengine mode. In addition, Emacs features that provide +support for several major modes configure ElDoc to use their +facilities for retrieving the documentation. Examples include Eglot +(@pxref{Eglot Features,,, eglot, Eglot: The Emacs LSP Client}), which +provides documentation based on information from language servers; +Semantic's Idle Summary mode (@pxref{Idle Summary Mode,,, semantic, +Semantic Manual}); and Flymake, which uses ElDoc to show diagnostics +at point (@pxref{Finding diagnostics,,, flymake, GNU Flymake manual}). + +The ElDoc mode works by scheduling the display of the available +documentation for the symbol at point after Emacs has been idle for +some short time. This avoids annoying flickering of documentation +messages in the echo area or the mode line when you type quickly and +without delay. + +@findex eldoc-print-current-symbol-info +You can also trigger the display of documentation for a symbol at +point by using the command @kbd{M-x eldoc-print-current-symbol-info}. + + The following variables can be used to configure ElDoc mode: + +@vtable @code +@item eldoc-idle-delay +The value of this user option controls the amount of idle time before +the at-point documentation is displayed. It should be set to the +number of seconds to wait; the value of zero means to display without +any delay. the default is 0.5 sec. + +@item eldoc-print-after-edit +If this user option is non-@code{nil}, ElDoc will show documentation +only after some editing command, like inserting or deleting some +text. This comes in handy if you want Emacs to display documentation +only about symbols that you type, but not about symbols that are +already in the buffer (so just reading the source code will not show +documentation). The default value is @code{nil}. If you change the +value, you need to toggle @code{eldoc-mode} off and on again. + +@item eldoc-echo-area-use-multiline-p +This user option controls whether and how to truncate documentation +text if it is longer than the echo-area can display as a single screen +line. If the value is a positive number, it specifies the number of +screen lines that ElDoc is allowed to display in the echo area without +truncating the documentation. A positive integer specifies the +absolute maximum number of screen lines to use; a floating-point +number specifies the number of screen lines as a fraction of the +frame's height. The value of @code{t} means never truncate the +documentation (the echo-area will be resized up to the height allowed +by @code{max-mini-window-height}, @pxref{Minibuffer Edit}), whereas +the value of @code{nil} means truncate if the documentation is longer +than a single screen line. Finally, the special value +@code{truncate-sym-name-if-fit} (the default) means to truncate the +part of the documentation that represents a symbol's name if doing +that will allow the documentation to fit on a single screen line. + +@item eldoc-echo-area-display-truncation-message +If non-@code{nil} (the default), and documentation shown in the echo +area is truncated because it's too long, follow the documentation by +instructions about how to view the complete documentation text. If +@code{nil}, just indicate with @samp{@dots{}} that the documentation +was truncated. + +@findex eldoc-doc-buffer +@item eldoc-echo-area-prefer-doc-buffer +If the value of this user option is @code{t}, ElDoc will not show the +documentation in the echo area if the ElDoc buffer with the +documentation is already displayed in some window. (You can use the +command @kbd{M-x eldoc-doc-buffer} any time to show the ElDoc buffer.) +If the value of this option is the symbol @code{maybe}, the +documentation will not be displayed in the echo area if the ElDoc +buffer is shown in some window and the documentation text has to be +truncated if displayed in the echo area. Finally, the value of +@code{nil} (the default) means always show the documentation in the +echo area. -@table @code @item eldoc-documentation-strategy -This variable holds the function which is used to retrieve -documentation for the item at point from the functions in the hook -@code{eldoc-documentation-functions}. By default, -@code{eldoc-documentation-strategy} returns the first documentation -string produced by the @code{eldoc-documentation-functions} hook, but -it may be customized to compose those functions' results in other -ways. +This customizable variable's value is the function which is used to +retrieve and display documentation for the symbol at point. The +documentation is produced by the functions in the hook +@code{eldoc-documentation-functions}. The default value of +@code{eldoc-documentation-strategy} specifies that ElDoc should +display the first documentation text produced by functions in the +@code{eldoc-documentation-functions} hook, but you can customize +@code{eldoc-documentation-strategy} to work in other ways, such as +displaying all of the documentation texts concatenated together. @item eldoc-documentation-functions -This abnormal hook holds documentation functions. It acts as a -collection of backends for ElDoc. This is what modes should use to -register their documentation functions with ElDoc. - -@vindex eldoc-echo-area-display-truncation-message -@item eldoc-echo-area-display-truncation-message -If non-@code{nil} (the default), display a verbose message about how -to view a complete documentation (if it has been truncated in the echo -area). If @code{nil}, just mark truncated messages with @samp{...}. -@end table +This abnormal hook's value is a list of functions that can produce +documentation for the symbol at point as appropriate for the current +buffer's major-mode. These functions act as a collection of backends +for ElDoc. Major mode register their documentation lookup functions +with ElDoc by adding their functions to the buffer-local value of this +variable. +@end vtable @node Hideshow @section Hideshow minor mode diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index ea1e086ebf1..1074a8a8292 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -718,9 +718,9 @@ byte-compiling any of the two files has equivalent results. The shorthands @code{snu-split} and @code{snu-lines} used in the second version are @emph{not} interned in the obarray. This is easily seen by moving point to the location where the shorthands are used and -waiting for ElDoc (@pxref{Lisp Doc, , Local Variables in Files, emacs, -The GNU Emacs Manual}) to hint at the true full name of the symbol -under point in the echo area. +waiting for ElDoc (@pxref{Programming Language Doc, , Local Variables +in Files, emacs, The GNU Emacs Manual}) to hint at the true full name +of the symbol under point in the echo area. Since @code{read-symbol-shorthands} is a file-local variable, it is possible that multiple libraries depending on diff --git a/doc/misc/octave-mode.texi b/doc/misc/octave-mode.texi index 31d64c3d840..d7ea54198ad 100644 --- a/doc/misc/octave-mode.texi +++ b/doc/misc/octave-mode.texi @@ -204,9 +204,10 @@ The GNU Emacs Manual}). Currently, function names can be indexed. @cindex ElDoc Mode Support @vindex octave-eldoc-message-style -ElDoc mode (@pxref{Lisp Doc,,, emacs, The GNU Emacs Manual}) is -supported. By customizing @code{octave-eldoc-message-style} it can be -changed from displaying one or multi line hints. +ElDoc mode (@pxref{Programming Language Doc,,, emacs, The GNU Emacs +Manual}) is supported. By customizing +@code{octave-eldoc-message-style} it can be changed from displaying +one or multi line hints. @c @cindex TAGS @c @cindex Emacs TAGS files diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index 3141ab7c692..36e09b152e5 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -621,7 +621,7 @@ Run the Semantic idle work function with debugging turned on. Semantic Idle Summary mode is a minor mode that displays a short summary of the symbol at point, such as its function prototype, in the echo area. Its functionality is similar to what ElDoc mode provides -for Emacs Lisp (@pxref{Lisp Doc,,,emacs,Emacs manual}). +for Emacs Lisp (@pxref{Programming Language Doc,,,emacs,Emacs manual}). @deffn global-semantic-idle-summary-mode &optional arg This command toggles Semantic Idle Summary mode in all 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." -- 2.39.5