bug#43609: 28.0.50; eldoc-documentation-function

[João Távora]

martin rudalics <rudalics@gmx.at> writes:

> so if it did not work for the modes you cite, the doc-string should have
> warned about that fact earlier.

IME when these docstrings are built, they don't foresee all possible
uses.  It didn't foresee the async use just like it didn't foresee your
direct call use.

> While this is certainly not your fault,
> changing the semantics of that variable for elisp-mode with the argument
> that it did not work for other modes was not a user-friendly step.

I don't really believe I changed the semantics, Martin.  I don't read
anywhere in the docstring that you are to funcall the value stored in
the variable eldoc-documentation-function, merely a description of the
protocol of that the function that you store there should do.  I do
understand that it might be seen as ambiguous by a newcomer, but you're
not exactly a newcomer, right?  :-)

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.

That said I am aware that in Emacs/Lisp _anything_ can happen :-) 

> Personally I use eldoc for two major modes only: 'emacs-lisp-mode' and
> 'c-mode' (in a crippled way via 'c-eldoc' but here nobody ever bothered
> to write an 'eldoc-documentation-function' function for one of the two
> major languages used to implement Emacs).

If you use the Eglot (or the lsp-mode) extension, you will see there are
increasingly nice solutions for that.

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

>> This is to clarify that the "direct call" protocol of Emacs 27's
>> eldoc.el was _never_ "a thing".  At any rate it was never something you
>> could rely on generally.
>
> At the time "el" in eldoc stood for elisp it was.  But many things
> changed since then, admittedly.

I agree.  Eldoc is now, and has been for a while, Emacs's de facto (and
only) framework for displaying documentation of things at point.  This
is why it's a piece very much worth improving.

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

>> However, its semantics depends on
>> your use case:
>>
>> - 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.

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

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

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

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.

>> If the former, you can probably do this (or some variation):
>>
>> (defun martin ()
>>    "CAUTION: Only works in default Emacs Lisp mode or modes with all-sync
>> docstring generating functions.  If some functions calls the
>> callback afterwards, that result is discarded."
>>    (let (res)
>>      (run-hook-with-args 'eldoc-documentation-functions
>>                          (cl-function
>>                           (lambda (doc &key thing face &allow-other-keys)
>>                             (push (format "%s: %s"
>>                                           (propertize
>>                                            (format "%s" thing)
>>                                            'face face)
>>                                           doc)
>>                                   res))))
>>      (mapconcat #'identity res "\n")))
>>
>
> Works without problems for elisp-mode.  Many thanks.

You're welcome.

> Now for c-mode I use
>
>       (set (make-local-variable 'eldoc-documentation-function)
>          'c-eldoc-print-current-symbol-info)
>
> What can I do here? The same?

In this case you just call c-eldoc-print-current-symbol-info, right?  Of
course you can _also_ do the former, if you wish, it's just like it
looks like you're not using the ElDoc framework anyway (though I haven't
read your attached tooltip.el code).

>> If the latter, I suggest you look at the code I have in the
>> scratch/eldoc-display-functions branch, which seems to match your
>> intentions/use case very closely.  The docstring of the new
>> eldoc-display-functions variable could be of use (let me know if it's
>> insuficcient).  This means your advanced tooltip-displaying technology
>> could now work with every Eldoc mode that uses the "new" protocol
>> (including, of course, Elisp mode).
>
> OK.  I will look into that later.

I'll look at your tooltip.el code and try to make a member function of
eldoc-display-function for it.

> My other interlocutor here was Dmitry Gutov.  Please refer to him with
> his name.

I fully understand that, and normally I would, but this is a special
case of very toxic communication.  So, for the moment, please permit me
to keep my distance, so we can make real progress on this bug.

> And I highly appreciate the fact that he was the only person to answer
> my bug report within a day or two.

Pity the answer didn't help you much.  I don't have time to browse
bug-gnu-emacs daily, sorry.  As I said, next time try to include me
directly.  You also can usually find active maintainers of specific
files (and even regions) with M-x vc-print-log or M-x vc-region-history.

Yours sincerely,
João