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

[João Távora]

> Let's disagree on the backward incompatibility issue.  As a rule, Emacs
> changes have always tried to not alter the signatures of functions in a
> way that makes previously written calls invalid but I'm not very eager
> to argue about that.

I don't think this is a detail we can paper over, it's quite central of
what happened to you. eldoc-documentation-function has a name that ends
in "function", but it is _not_ a function.  It is a variable.  The fact
is that you were are funcalling _a variable_, not a _function_.  The
instructions in the docstring for that variable teach you, as they have
always, how to create values to assign to that variable.

There are very many variable variables in Emacs core alone ending in
"function" (just M-x apropos-variable for them).  They are called by the
libraries that define them, in potentially special contexts (say, with
special variables or unwind-protect around them).  If you create code
that funcalls the values without reconstructing these conditions
perfectly (a futile exercise IMO) you run the same risks of breakage
that you run when relying on implementation details.

Also, even before my changes, there was a better way to do what you
wanted (and there still is, afaik), which was (is) to hook onto
eldoc-message-function (Yuan Fu's code does this, though it doesn't use
a tooltip, it uses a so-called "child-frame").

Now, after my changes, your options to do your library correctly have
only increased.

> For me the sad fact remains that I will now have to change all these
> calls on my 50-some Winchester and USB partitions where I have Emacs
> installed, whenever I plug in or reactivate any of them and the
> respective error message pops up rendering the actual session invalid.

I'd like to help you, but I don't understand: are you updating Emacs to
master in all 50 of those drives?  Do you do this 50 times?  By hand?
Why can't you update your eldoc-tooltip.el in the process?

> Something you could have avoided by keeping a clean separation of the
> old behavior of 'eldoc-documentation-function' on the one side and the
> new behavior of 'eldoc-documentation-functions' on the other.

I don't understand how this can work: it's essential that ElDoc calls
eldoc-documentation-functions _through_ eldoc-documentation-function:
that's the only way it can deal with both old-style libraries that set
the latter and new-style library that set the former.  That's the key to
backward compatibility, and it's working correctly for many old and new
packages.  Furthermore, this link between the two variables _precedes_
my code (see SHA c0fcbd2c119b8418855f0931aceefbef717c5e53): I just added
the async support.

> Please everybody keep in minnd for future changes to avoid introducing
> such incompatible behavior.  If there is a function definition and
> that function is not clearly marked as internal (via the usual two
> slashes), please keep the signature and the semantics intact so users
> can rely on it behaving as intended until that function has been
> declared obsolete for a sufficient long time.

If "function definitions" were at stake, I would certainly agree with
you.  But they're not.  This is a _variable_ definition, that the
library gives users to exert control by assigning to it, _not_
funcalling it.  The semantics pertain to what values users are allowed
to assign to it.  Those semantics have been kept intact.  When libraries
mean for users to _call_ something, they expose functions, not
variables.

> I still have to make the change in all copies of my library I intend to
> run.  While this may look like a minor issue to you, it would make Emacs
> in the long term unusable for me, if such changes were introduced on a
> regular basis.

I have no idea if it's minor or major: I don't mean to belittle your
troubles, I'm trying to help you.  But I also don't understand this. As
I recall I've given you two modified version of your library:

- The one uses a martin() function and makes it work with all Emacsen
  but disregards asynchronous backends.  It seems to be enough for your
  use case anyway.
 
- The other uses the new protocol properly, removed much of your ElDoc
  reinvention, and works with the latest Emacs.  If you find a way to
  load the latest eldoc.el, it works with Emacs >= 26.3

If you are going to update Emacs to master in N servers, you might as
well update your library in those N servers. If you're updating it by
hand, then this doesn't seem like a tremendous extra effort to expend.
If you're using a script, just put the library update in that script.  I
personally use Git to good effect for this: push once, pull many times.

Alternatively, and perhaps even better, you're invited to contribute
your library to Emacs (or GNU ELPA).  Then you'll just have to update
Emacs, using your preferred method.

>> But a much better alternative, in my opinion, is to use the code I gave
>> you and create a robust package that works correctly in Emacs >= 26.3.
>> How?  You make use of the fact the latest ElDoc in master is now _also_
>> available in GNU ELPA
> Since I don't use any package archives and do not require them, this is
> not a practical option for me.

If you don't like packages, then just arrange some way for the latest
eldoc.el to be loaded along with martin-tooltip.el.  Eldoc.el has no
other dependencies other than Emacs 26.3.

João