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

[João Távora]

martin rudalics <rudalics@gmx.at> writes:

> But how can I get that default mentioned in "By default,
> ‘eldoc-documentation-function’ returns the first documentation string
> produced by the ‘eldoc-documentation-functions’ hook."?

It's still the default.  But I see your confusion.  Instead of:

   "returns the first documentation string produced ..."

It should say:

   "computes the first documentation string produced"

Or even:

   "arranges for the first documentation string produced ... to be
   displayed to the user"

These things are, of course, equivalent from the POV of the user as long
as you're not calling eldoc-documentation-function, the variable.

This is also shows what async does: If doc string are to be produced
asynchronously, then by definition eldoc-documentation-function cannot
return it as a Lisp return value.

>> But there's still something I don't understand: in your original
>> martin-tooltip.el library you didn't call this e-e-d-f function, did
>> you?  AFAIU, you did:
>>
>>     (funcall eldoc-documentation-function)
>>
>> or am I mistaken?
>
> You're not mistaken.  My expectation was and would be that in elisp mode
> 'eldoc-documentation-function' returned the value produced by
> 'elisp-eldoc-documentation-function' and IIUC that can't be done any
> more because it would break you compatibility code for that variable.

Yes but now _you're_ mistaken.  You _can_ still set `e-d-f` to `e-e-d-f`
and that still works.  But the default in Elisp mode is to make use of
`e-d-f`'s (also known as eldoc-documentation-strategy) superior
capabilities that allow it to report more than one type of doc per
symbol, for example.

>> So you'd have to change your code anyway to now call
>> elisp-eldoc-documentation-function, right?  So, if you're going to
>> change it, why not change it to the new, better alternatives I have
>> presented?
>
> Because at the time I'm there I have other concerns than remember how I
> did that.

I didn't follow this at all, but it seems highly personal and related to
how your mental memory works, so I'm not going to insist.  I just think
a code change is a code change and I've given you the code.

> With your changes, I cannot simply customize a variable to get the old
> behavior back.  I have to do some extra coding somewhere.

I'd say customize a variable and do some extra (trivial) coding are
comparable in effort, especially when someone else is handing you that
code.

>> of Emacs in those drives/servers/hosts where an incompatible
>> martin-tooltip.el lives?  I just don't understand why updating an Emacs
>> executable is somehow feasible in that setup but updating an Elisp
>> library that it depends on isn't.
> Because I expect Emacs to be backward-compatible (.elc included).

We've gone through that, and I've noted that your library was calling a
variable (not a functino) meant to be called by a library.  That's
relying on an implementation detail, and Emacs's implementation changes
over time.

>> I'm again confused: If you contribute your code to Emacs, then whenever
>> you update Emacs (which seems to be what you're concerned about) the
>> facilities you need will just be there.
>
> But my .emacs won't know.

But your .emacs has to know about "custom-set-variables" too right?  Why
are you OK with that?

>> As promised, a patch for you to review (and maybe Lars as well?)
>
> Thank you.  If it also provided an option so the only thing I'd have to
> do is to customize that, things would become for me as simple as the
> present situation permits, I think.

You can:

 (add-hook 'emacs-lisp-mode-hook
           (lambda () (setq-local eldoc-documentation-function
                                  'elisp-eldoc-documentation-function)))

Somewhere in your .emacs.  Or in your martin-tooltip.el library.

Frankly, I think a customization variable for this type of obsoleted
behaviour is too much.  I get that deleting
elisp-eldoc-documentation-function was getting rid of a non '--'
function that, even though:

- it's quite questionable that third parties should be relying on it,
- noone in the core Emacs relied upon it,
- and noone in GNU Elpa relied upon it,
- and not even your private martin-tooltip.el code relied upon it,

So we bring that e-e-d-f back, OK seems it _could_ help you make the
adaptation of martin-tooltip.el, even though I've given you already
multiple better adaptations of that same file that you reject for some
reason that I can't comprehend.

But changing the _value_ of eldoc-documentation-function (the variable)
was _not_ a backward incompatible change (I've explained at length why,
I think).  So a confusing user option here to save you those three lines
of trivial code seems too much.

João