bug#43609: 28.0.50; eldoc-documentation-function [vs new eldoc-display-functions]

[martin rudalics]

> But changing the _value_ of eldoc-documentation-function (the variable)
> was _not_ a backward incompatible change

And I disagree.

(1) Fifteen years ago we had

(defvar eldoc-documentation-function nil
  "If non-nil, function to call to return doc string.
The function of no args should return a one-line string for displaying
doc about a function etc. appropriate to the context around point.
It should return nil if there's no doc appropriate for the context.
Typically doc is returned if point is on a function-like name or in its
arg list.

This variable is expected to be made buffer-local by modes (other than
Emacs Lisp mode) that support Eldoc.")

(2) Five years ago, that is, at the time I wrote 'eldoc-tooltip-mode' we
had

(defvar eldoc-documentation-function #'ignore
  "Function to call to return doc string.
The function of no args should return a one-line string for displaying
doc about a function etc. appropriate to the context around point.
It should return nil if there's no doc appropriate for the context.
Typically doc is returned if point is on a function-like name or in its
arg list.

The result is used as is, so the function must explicitly handle
the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p',
and the face `eldoc-highlight-function-argument', if they are to have any
effect.

Major modes should modify this variable using `add-function', for example:
  (add-function :before-until (local 'eldoc-documentation-function)
                #'foo-mode-eldoc-function)
so that the global documentation function (i.e. the default value of the
variable) is taken into account if the major mode specific function does not
return any documentation.")

(3) With

commit c0fcbd2c119b8418855f0931aceefbef717c5e53
Author: Mark Oteiza <mvoteiza@udel.edu>
Date:   Tue Feb 25 17:53:04 2020 -0500

    Expose ElDoc functions in a hook (Bug#28257)

the definition became

(defcustom eldoc-documentation-function #'eldoc-documentation-default
  "Function to call to return doc string.
The function of no args should return a one-line string for displaying
doc about a function etc. appropriate to the context around point.
It should return nil if there's no doc appropriate for the context.
Typically doc is returned if point is on a function-like name or in its
arg list.

The result is used as is, so the function must explicitly handle
the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p',
and the face `eldoc-highlight-function-argument', if they are to have any
effect."

(4) With current master 'eldoc-documentation-function' is not defined
any more but has become an alias in a way I can't fathom.  C-h v gets
me:

eldoc-documentation-function is a variable defined in ‘eldoc.el’.
Its value is ‘eldoc-documentation-default’

  This variable is an alias for ‘eldoc-documentation-strategy’.
  You can customize this variable.
  Probably introduced at or before Emacs version 22.1.

Documentation:
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
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.

For backward compatibility to 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.

Note here the "can also be set to a function of no args that returns
something other than a string or nil" and "For backward compatibility to
the \"old\" protocol, this variable can also be set to a function that
returns nil or a doc string": The former implies that returning a string
or nil is the expected behavior.  The latter implies that returning a
string or nil is the exception.

What makes (4) backward incompatible is that "should return a one-line
string" is no more mentioned in the doc-string.  Consequently, modes
defining their support functions do not have to support this part of the
original specification any more.  In the sequel changes were installed
that, for example, have the corresponding function in elisp-mode.el
return a value that no more obeys the doc-strings of (1), (2) and (3).

It's also possible that the incompatible change is a combination of (3)
and (4): (3) changed the implementation in a way that already violated
the semantics of 'eldoc-documentation-function' by silently accepting
return values that at the time (3) was installed were invalid according
to its doc-string.  (4) then sanctioned that violation by aliasing the
variable and amending the doc-string.

> (I've explained at length why, I think)

So let's continue to disagree.

martin