Re: eldoc-docstring-format-sym-doc

[João Távora]

Frank Haun <fh@fhaun.de> writes:

> On Sun, 26 Jul 2020 11:16:31 +0100, João Távora wrote:
>
>> Here's a patch that should fix this, by bringing back the function to
>> eldoc and marking it obsolete.  I'd of course much prefer if Elpy starts
>> using the new features of eldoc-documentation-functions instead, if
>> indeed it must be made to work with Emacs 28.  The bits of that
>> variable's docstring concerning the `:THING` and `:FACE` keyword
>> arguments should, in principle, be enough to do the same as the defunct
>> eldoc-docstring-format-sym-doc.  If they're not, then it's something to
>> be iterated in eldoc.el.
>
> Someone made an elpy issue of the missing eldoc-docstring-format-sym-doc
> function:
>
>   https://github.com/jorgenschaefer/elpy/issues/1823

Thanks.  I've commented on the issue and drafted a patch for Elpy the
should make it work with the older and newer Eldoc versions.  I'm kind
of against applying the patch I provided earlier: it is true that I
advertised the enhancements to ElDoc as backward-compatible and it's
clearly they are not 100% so, even if eldoc-docstring-format-sym-doc
is an implementation detail.

But I'd like to see more evidence that this is breaking many more places
than Elpy, where the fix is easy.  After a quick GitHub code search,
that doesn't seem to be the case.

Also, after examining Elpy's uses of ElDoc, I noticed at least two
places where Elpy could take advantage of the new ElDoc:

- Elpy's elpy-eldoc-documentation is serving Flymake diagnostic info as
  ElDoc documentation.  If a diagnostic is at point, ElPy serves it and
  stops there.  There is no need to do that in the latest versions of
  Flymake and ElDoc, where this is the default behaviour;

- Beyond this, Elpy's elpy-eldoc-documentation is also serving multiple
  other kinds of Python documentation about the "thing at point".  If it
  were to be split in various functions, it would not be forced to
  choose among them using fixed rules.  It could provide "calltips",
  "oneline docs", simple strings, and "current function" info
  independently, then have the user (or ElPy) arrange some priority in
  the eldoc-documentation-functions hook, where asynchronous and
  synchronous sources can now be intermingled seamlessly.  The new
  variable eldoc-documentation-strategy decides how to compose those
  multiple sources of documentation.

João