bug#45348: 27.1; python-eldoc-setup-code uses obsolete python function

[João Távora]

Tomas Nordin <tomasn@posteo.net> writes:

>> All of those things have been touched recently by me, and I'd appreciate
>> the feedback.
>
> OK, thanks. Then we know the API to read up on when it comes to that.
>
> I would be happy to try and help improving the doc support in python.el.
> The strategy I would suggest to do that would be
>
> -- C-c C-d         python-describe-at-point
>
> Make this display full documentation akin to C-h f in elisp. Document

> -- Automatic help display of objects
>
> Make this show signatures always. (akin to elisp mode).
>
> But I don't know if anybody care to see this happen.

I would.  Or at least I think these ideas are welcome input for solving
the broader problem of inconsistency of documentation systems in Emacs.
In fact, I'm going to take this opportunity to lay out a plan that I've
been thinking of, to collect some early feedback, and to seize on any
motivation that you or someone else may have to work on this.

I quite agree with you when you say there is something that should
display full documentation akin to C-h f in Elisp.  But this is not only
for Python, it is for all languages -- including Elisp.

In my opinion, that something should be 'M-x eldoc' (and we can chose a
prominent shortcut for it later).  In the latest Emacs, when invoked
interactively, it pops up a new buffer (like C-h f does) which contains
detailed information about how to use a particular element of the
language (a function, a procedure, a variable, etc).  When invoked
automatically by a background process, it behaves more discreetly, but
and normally displays a shorter string in the echo area.

Under the hood, the ElDoc framework also now possesses the main tools to
help segregate succint short summaries that can be shown in a
constrained setting -- such as the echo area -- from longer descriptions
that are more suitable for larger outlets, such as buffers, separate
frame and long-winded popup widgets.  These tools are the aforementioned
eldoc-documentation-functions and eldoc-display-functions.

In my view we're only missing a protocol for the former to communicate
to the latter how small or large the produces pieces of documentation
are.  How?  Here's the current situation in Elisp mode: M-x eldoc will
call on one or two backends (sometimes both, depending on
eldoc-documentation-strategy) to document the thing at point: the
variable documentation one and the function documentation one.  For
historical reasons, they return simple one liners for displaying in the
echo area.  But each could _additionally_ return much richer
descriptions like the ones that C-h v and C-h f do.  They could return
this in new a :FULL-DOC property:

* eldoc-display-in-echo-area would ignore it, since it is content
  that doesn't fit its target:

* eldoc-display-in-buffer function would utilize to format a buffer
  that would look much like the *Help* buffer does nowadays.

Whether that new property should be a string, a function, a buffer, or
any of the above is an implementation detail we'd have to think up.
Regardless, I'm sure something like this could be thought up for some
future Python backend(s) as well: an Eldoc backend that returns a short
summary (the signature, presumably) and a longer description of the
thing at point.

Other pieces of the puzzle to consider here are the somewhat
underused/defunct help-at-pt.el which happens to have a good shortcut in
'C-h .'.  It could be merged with ElDoc and lend that shortcut to M-x
eldoc.

João