[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: eldoc-docstring-format-sym-doc
From: |
João Távora |
Subject: |
Re: eldoc-docstring-format-sym-doc |
Date: |
Mon, 27 Jul 2020 15:52:51 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) |
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