bug#43609: 28.0.50; eldoc-documentation-function

[martin rudalics]

> 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
> these variable indirections in the first place, it's because they expect
> to be able to call them in the contexts of their choosing.  So it never
> crossed my mind, or my eyes that one would be expecting to use it like
> that, neither did anyone specifically call attention to this and/or
> provided an example.

We probably should be more defensive when writing doc-strings for such
variables.

>> 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'.

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

>>> 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?

>>> - Do you want to have a return value handy for the docstrings that are
>>>     immediately available from the sources that respond synchronously?
>>
>> Definitely.
>
> That would be very close to the `martin` function I gave you earlier.

Yes.

>>> - Do you want to wait actively until all sources have reported back and
>>>     then get a return value?  In this case, do you need a timeout?
>>
>> If we can provide an option for that, yes.
>
> It's easy to do (Eldoc's current version has to do it already).

OK.

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

> 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)?

martin