28.6.3 Programming Language Documentation Lookup

When editing Emacs Lisp code, you can use the commands C-h f (describe-function) and C-h v (describe-variable) to view the built-in documentation for the Lisp functions and variables that you want to use. See Help by Command or Variable Name.

ElDoc¹⁵ 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 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 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 (see Eglot Features in Eglot: The Emacs LSP Client), which provides documentation based on information from language servers; Semantic’s Idle Summary mode (see Idle Summary Mode in Semantic Manual); and Flymake, which uses ElDoc to show diagnostics at point (see Finding diagnostics in 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.

You can also trigger the display of documentation for a symbol at point by using the command M-x eldoc-print-current-symbol-info.

The following variables can be used to configure ElDoc mode:

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.

eldoc-print-after-edit ¶

If this user option is non-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 nil. If you change the value, you need to toggle eldoc-mode off and on again.

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 t means never truncate the documentation (the echo-area will be resized up to the height allowed by max-mini-window-height, see Editing in the Minibuffer), whereas the value of nil means truncate if the documentation is longer than a single screen line. Finally, the special value 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.

eldoc-echo-area-display-truncation-message ¶

If non-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 nil, just indicate with ‘…’ that the documentation was truncated.

eldoc-echo-area-prefer-doc-buffer ¶

If the value of this user option is 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 M-x eldoc-doc-buffer any time to show the ElDoc buffer.) If the value of this option is the symbol 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 nil (the default) means always show the documentation in the echo area.

eldoc-documentation-strategy ¶

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 eldoc-documentation-functions. The default value of eldoc-documentation-strategy specifies that ElDoc should display the first documentation text produced by functions in the eldoc-documentation-functions hook, but you can customize eldoc-documentation-strategy to work in other ways, such as displaying all of the documentation texts concatenated together.

eldoc-documentation-functions ¶

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 modes register their documentation lookup functions with ElDoc by adding their functions to the buffer-local value of this variable.