Variable: eldoc-documentation-functions

eldoc-documentation-functions is a variable defined in eldoc.el.gz.

Documentation

Hook of functions that produce doc strings.

A doc string is typically relevant if point is on a function-like 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 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
  return either the doc string, or nil if there's no doc
  appropriate for the context.

- If the computation of said doc string (or the decision whether
  there is one at all) is expensive or can't be performed
  directly, the hook function should return a non-nil, non-string
  value and arrange for CALLBACK to be called at a later time,
  using asynchronous processes or other asynchronous mechanisms.

To call the CALLBACK function, the hook function must pass it an obligatory argument DOCSTRING, a string containing the documentation, followed by an optional list of arbitrary keyword-value pairs of the form (:KEY VALUE :KEY2 VALUE2...). The information contained in these pairs is understood by members of eldoc-display-functions, allowing the 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
  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
  eldoc-display-functions, sometimes omits this information
  depending on space constraints;

* :face, VALUE being a symbol designating a face which both
  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)
so that the global value (i.e. the default value of the hook) is taken into account if the major mode specific function does not return any documentation.

View in manual

Probably introduced at or before Emacs version 28.1.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/eldoc.el.gz
(defvar eldoc-documentation-functions (list #'eldoc-show-help-at-pt)
  "Hook of functions that produce doc strings.

A doc string is typically relevant if point is on a function-like
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 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
  return either the doc string, or nil if there's no doc
  appropriate for the context.

- If the computation of said doc string (or the decision whether
  there is one at all) is expensive or can't be performed
  directly, the hook function should return a non-nil, non-string
  value and arrange for CALLBACK to be called at a later time,
  using asynchronous processes or other asynchronous mechanisms.

To call the CALLBACK function, the hook function must pass it an
obligatory argument DOCSTRING, a string containing the
documentation, followed by an optional list of arbitrary
keyword-value pairs of the form (:KEY VALUE :KEY2 VALUE2...).
The information contained in these pairs is understood by members
of `eldoc-display-functions', allowing the
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
  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
  `eldoc-display-functions', sometimes omits this information
  depending on space constraints;

* `:face', VALUE being a symbol designating a face which both
  `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)
so that the global value (i.e. the default value of the hook) is
taken into account if the major mode specific function does not
return any documentation.")