bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Hello,

As I recently mentioned to Lars over at bug#32243, the recent changes to
ElDoc have made it possible for the user and the major mode to control
the information that is eventually showed to the user in the echo area.
That bug, which concerned Elisp function signatures overriding/hiding
Flymake diagnostic lines, has been fixed, mostly because Flymake itself
is an independent producer of Eldoc information, and one is now given
the tools to coordinate between different sources.

The TL;DR is that this bug is a proposal for changing the default value
of `eldoc-documentation-strategy` to `eldoc-documentation-compose`, in
Elisp mode so that all these sources can serve us simultaneously.

So, in Emacs master, we have reasonably common sources for Elisp mode,
which may all act and be useful at the same time.  They occupy this
relative order in 'eldoc-documentation-functions':

- elisp-eldoc-funcall
- elisp-eldoc-var-docstring
- flymake-eldoc-function  (only active if Flymake mode is enabled)

I've recently moved `flymake-eldoc-function` from first to the last spot
in the list.  If I hadn't done that, the default behaviour when writing
a sexp such as, say:

   (my-dear-function [point here])

would be to foremost greet the user with the Flymake error message about
insufficient args being supplied to the `my-dear-function` call about to
be written, rather than what those args are supposed to be.  Obviously
this defeats the purpose of having ElDoc serve as a code-writing aid.

But now take this other situation and suppose there is an error in the
"foo" where point is on:

   (my-dear-function 'fo[point here]o 42 'bar)

Having the sexp written with a suitable number of arguments but with
some Flymake mistake will now fail to notify us of those mistakes, since
the signature information takes priority.  This is similar, if not the
same, as the aforementioned bug#32243.

Earlier, there was no obvious solution to this, especially if one
insisted on using only a one-line-tall echo area at the maximum.  Now,
after Mark Oteiza's introduction of `eldoc-documentation-functions`,
there are ways to configure suitable behaviours.  In particular there is
`eldoc-documentation-strategy` (formerly `eldoc-documentation-function`,
singular), which tells how to coordinate ElDoc information from multiple
sources.

This variable's value defaults to `eldoc-documentation-default`
globally. I suggest we default it to `eldoc-documentation-compose` in
Elisp mode, so the three functions occupying
`eldoc-documentation-functions` can be in play at the same time.  This
is because the information conveyed by them can be generally be useful
at the same time.

If that creates too tall an echo area for some, I want to mention that,
for now, there is the variable `eldoc-echo-area-use-multiline-p` to
control this.  For those willing to bear with 2 lines at most, I think
this is guaranteed.  For non-users of Flymake, for instance, 2 lines
usually happens if one lands the cursor on documented Elisp variable
being used inside a documented function.  With the cursor on the first
argument in this form:

   (run-with-idle-timer eldoc-idle-delay nil ...)

The echo area would show two lines instead of the usual 1:

    eldoc-idle-delay: Number of seconds of idle time to wait before printing.
    run-with-idle-timer: (SECS REPEAT FUNCTION &rest ARGS)

Also note that even if one sets `eldoc-echo-are-use-multiline-p` to nil,
or 1, one can still get the full set of lines by via M-x
eldoc-doc-buffer.

Later on, we will probably want to review and explore other outlets
other than the echo area and this auxiliary buffer for displaying the
information collected and coordinated by our chose
eldoc-documentation-strategy.

But that is matter for another bug report...

João