bug#43609: 28.0.50; eldoc-documentation-function

[João Távora]

martin rudalics <rudalics@gmx.at> writes:

>> Maybe there are examples but I can't find a single example of a user
>> variable ending in "-function" that's supposed to work like you describe
>> or that explicitly advocates for it/against it.  If libraries establish
> We probably should be more defensive when writing doc-strings for such
> variables.

Maybe, but none of the docstrings of foo-bar-function variables I
consulted explicitly say that you shouldn't call them directly and that
that task is reserved for foo.el.  But that's factually how they work.
When foo.el intends for a function to be called by programs it usually
provides 'foo-bar', the function, not 'foo-bar-function', the variable.

>>> And as far as the former is concerned, I now cannot use even
>>> 'elisp-eldoc-documentation-function' directly either because you
>>> changed its return value too.
>>
>> I looked up uses of that function in the Emacs source tree and couldn't
>> find any.  Because of the reasoning explained above, I also expected
>> Elisp mode to be its sole reasonable user.
>
> Agreed if you meant to say that eldoc-mode would be the sole reasonable
> user of 'elisp-eldoc-documentation-function'.

Yes, that's what I meant.

>> But if you really insist , it's a very easy function to bring back I
>> would say (in fact the function I gave you earlier is probably more
>> useful generalization of it).
>
> I won't insist if I have something that substitutes it.  And if you can
> provide that something within eldoc.el, a simple cross reference from
> the doc-string of 'eldoc-documentation-function(s)' would be enough.

eldoc-documentation-function (singular) is now obsolete.  If we do come
up with such a synchronous, direct-call, get-me-the-docs function, it
makes of course sense to document it somewhere.

>>>> If you need a direct call, "give me the string" entry point to the
>>>> eldoc.el library, one can be added.
>>>
>>> I think we should do that and provide it as compatibility layer for
>>> people like me who need it.
>>
>> OK.  Do you know very many of those?
>
> No.  Do you know anyone who displays eldoc outside of the echo area?

Indeed I do.  Yuan Fu is working on a eldoc-box extension that displays
documentation kind of a tooltip (a child frame I think it's called).

  https://github.com/casouri/eldoc-box/blob/master/eldoc-box.el

Its implementation should also be considerably simplified by the
upcoming eldoc-display-functions.  But currently it uses
eldoc-message-function which is not perfect for the async case.  At any
rate, it's more reliable than calling eldoc-documentation-function as
you used to do.

Additionally, eldoc.el itself can now display in a *eldoc for <thing>*
buffer (much as you suggest below).  In the latest branch, that is
handled by a display function called eldoc-display-in-buffer.

>>>> - Independent of your choice above, or do you want to get the return
>>>>     value as list of strings?  Or as a single string, maybe concatenated
>>>>     and propertized, exactly the way it is display[ed in the echo area].
>>>
>>> I'd prefer a list of strings.
>>
>> What about a slightly more complex type? (but not much)
>
> No objections.
>
>> As of now, "enriched" docstrings can be seen as the association of a
>> string with a number of properties, say the "thing" being documented, or
>> the preferred "face" to do it in.  Later on, a piece of documentation
>> can have, for example, other optional meta-hints about it, such as the
>> language or variations on itself for displaying under a very limiting
>> context (such as the echo area), or very permissive context (such as a
>> spacious Help-like buffer).
>
> I certainly would not mind a buffer (like *eldoc-latest*) that I could
> consult to obtain the latest information eldoc caught about the symbol
> at point of the selected window either.  Maybe together with some status
> indicator about how much of that information has been retrieved
> already.

I think your desired *eldoc-latest* buffer is the return value of the
nullary eldoc-doc-buffer function.  The buffer indeed has the "latest"
documentation, but it, by itself, currently doesn't tell you how many of
the eldoc-documentation-functions (plural) have yet to respond.

That knowledge exists and is held by internal mechanisms of eldoc.el.
We could expose it, but I prefer to avoid doing that unless a clear need
arises (that isn't handled by anything else).

>> So I think it the return value of such a function should thus be:
>>
>>      ...a list (DOC ...) where DOC looks like (STRING :KEY VALUE :KEY2
>>      VALUE2 ...).  STRING is the a possibly propertized string
>>      containing the documentation's text and the remainder of DOC is
>>      an optional list of keyword-value pairs, described in
>>     `eldoc-documentation-functions'.
>>
>> This will make the return value of the desired function match the values
>> given to eldoc-display-functions, which could come in advantageious.
>
> What, in a nutshell, would these 'eldoc-display-functions' be (sorry but
> my master on this system is in an inconsistent state and I don't want to
> resolve conflicts when pulling anything into it)?

No problem, here's the full docstring of the variable:

    (defvar eldoc-display-functions
      '(eldoc-display-in-echo-area eldoc-display-in-buffer)
      "Hook of functions tasked with displaying ElDoc results.
    Each function is passed two arguments: DOCS and INTERACTIVE. DOCS
    is a list (DOC ...) where DOC looks like (STRING :KEY VALUE :KEY2
    VALUE2 ...).  STRING is the a possibly propertized string
    containing the documentation's text and the remainder of DOC is
    an optional list of keyword-value pairs, described in
    `eldoc-documentation-functions'.
     
    INTERACTIVE says if the request to display doc strings came
    directly from the user or from ElDoc's automatic mechanisms'.")

Mind you, this is only a draft.  In particular, I wonder if point (and
mouse position?) at the time when eldoc.el decided to automatically
request documentation should also be passed in somehow.  Maybe we could
reuse the INTERACTIVE argument, which currently is non-nil only if user
specifically pressed M-x eldoc on a thing to document.

Yours sincerely,
João