eldoc-docstring-format-sym-doc

eldoc-docstring-format-sym-doc

[Frank Haun]

Hi,

when was the function "eldoc-docstring-format-sym-doc" removed? I cant
find nothing in the logs.

Elpy is using it.

Thanks,
Frank

Re: eldoc-docstring-format-sym-doc

[Tassilo Horn]

Frank Haun <fh@fhaun.de> writes:

Hi Frank,

> when was the function "eldoc-docstring-format-sym-doc" removed? I cant
> find nothing in the logs.

In this commit:

  commit 1203626f472b0d99d2746f5999711137c0c1fd0c
  Author: João Távora <joaotavora@gmail.com>
  Date:   Sat Jun 6 14:04:48 2020 +0100

> Elpy is using it.

It seems like it was removed including allmost all calls except for in
semantic/grammar.el:

    * lisp/cedet/semantic/grammar.el (semantic--docstring-format-sym-doc):
    New function.
    (semantic-grammar-eldoc-get-macro-docstring): Adjust.

Basically semantic--docstring-format-sym-doc is the old
eldoc-docstring-format-sym-doc.  But I guess the plan is to remove that
eventually, too.  Eldoc got a overhaul recently...

Bye,
Tassilo

Re: eldoc-docstring-format-sym-doc

[Frank Haun]

On Fri, 24 Jul 2020 21:49:12 +0200, Tassilo Horn wrote:

> Frank Haun <fh@fhaun.de> writes:
>
>> when was the function "eldoc-docstring-format-sym-doc" removed? I cant
>> find nothing in the logs.
>
> In this commit:
>
>   commit 1203626f472b0d99d2746f5999711137c0c1fd0c
>   Author: João Távora <joaotavora@gmail.com>
>   Date:   Sat Jun 6 14:04:48 2020 +0100
>
>> Elpy is using it.
>
> It seems like it was removed including allmost all calls except for in
> semantic/grammar.el:
>
>     * lisp/cedet/semantic/grammar.el (semantic--docstring-format-sym-doc):
>     New function.
>     (semantic-grammar-eldoc-get-macro-docstring): Adjust.
>
> Basically semantic--docstring-format-sym-doc is the old
> eldoc-docstring-format-sym-doc.  But I guess the plan is to remove that
> eventually, too.  Eldoc got a overhaul recently...

Ah ok. Thank you.

Frank

Re: eldoc-docstring-format-sym-doc

[Eli Zaretskii]

> From: Tassilo Horn <tsdh@gnu.org>
> Date: Fri, 24 Jul 2020 21:49:12 +0200
> Cc: emacs-devel@gnu.org
> 
> > when was the function "eldoc-docstring-format-sym-doc" removed? I cant
> > find nothing in the logs.
> 
> In this commit:
> 
>   commit 1203626f472b0d99d2746f5999711137c0c1fd0c
>   Author: João Távora <joaotavora@gmail.com>
>   Date:   Sat Jun 6 14:04:48 2020 +0100
> 
> > Elpy is using it.
> 
> It seems like it was removed including allmost all calls except for in
> semantic/grammar.el:
> 
>     * lisp/cedet/semantic/grammar.el (semantic--docstring-format-sym-doc):
>     New function.
>     (semantic-grammar-eldoc-get-macro-docstring): Adjust.
> 
> Basically semantic--docstring-format-sym-doc is the old
> eldoc-docstring-format-sym-doc.  But I guess the plan is to remove that
> eventually, too.  Eldoc got a overhaul recently...

João, based on this report, do we need some backward-compatibility
shim to help 3rd party packages which use this removed function?

Re: eldoc-docstring-format-sym-doc

[João Távora]

[-- Attachment #1: Type: text/plain, Size: 1606 bytes --]

On Sat, Jul 25, 2020 at 7:16 AM Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Tassilo Horn <tsdh@gnu.org>
> > Date: Fri, 24 Jul 2020 21:49:12 +0200
> > Cc: emacs-devel@gnu.org
> >
> > > when was the function "eldoc-docstring-format-sym-doc" removed? I cant
> > > find nothing in the logs.
> >
> > In this commit:
> >
> >   commit 1203626f472b0d99d2746f5999711137c0c1fd0c
> >   Author: João Távora <joaotavora@gmail.com>
> >   Date:   Sat Jun 6 14:04:48 2020 +0100
> >
> > > Elpy is using it.
> >
> > It seems like it was removed including allmost all calls except for in
> > semantic/grammar.el:
> >
> >     * lisp/cedet/semantic/grammar.el
> (semantic--docstring-format-sym-doc):
> >     New function.
> >     (semantic-grammar-eldoc-get-macro-docstring): Adjust.
> >
> > Basically semantic--docstring-format-sym-doc is the old
> > eldoc-docstring-format-sym-doc.  But I guess the plan is to remove that
> > eventually, too.  Eldoc got a overhaul recently...
>
> João, based on this report, do we need some backward-compatibility
> shim to help 3rd party packages which use this removed function?
>

From memory, maybe  just bringing back the function as-is should
do the trick, since eldoc-docstring-format-sym-doc is just a
string formatting function, I seem to recall.

I hope this can wait for monday, as I don't have much time
for emacs devel this weekend.

Ideally though, elpy would rely on the new API, if possible.
Is Elpy using the new eldoc.el because it's being started
with Emacs 28 or because it's fetching the package from
GNU ELPA?

João

[-- Attachment #2: Type: text/html, Size: 2406 bytes --]

Re: eldoc-docstring-format-sym-doc

[João Távora]

[-- Attachment #1: Type: text/plain, Size: 2229 bytes --]

João Távora <joaotavora@gmail.com> writes:

> On Sat, Jul 25, 2020 at 7:16 AM Eli Zaretskii <eliz@gnu.org> wrote:
>
>  > From: Tassilo Horn <tsdh@gnu.org>
>  > Date: Fri, 24 Jul 2020 21:49:12 +0200
>  > Cc: emacs-devel@gnu.org
>  > 
>  > > when was the function "eldoc-docstring-format-sym-doc" removed? I cant
>  > > find nothing in the logs.
>  > 
>  > In this commit:
>  > 
>  >   commit 1203626f472b0d99d2746f5999711137c0c1fd0c
>  >   Author: João Távora <joaotavora@gmail.com>
>  >   Date:   Sat Jun 6 14:04:48 2020 +0100
>  > 
>  > > Elpy is using it.
>  > 
>  > It seems like it was removed including allmost all calls except for in
>  > semantic/grammar.el:
>  > 
>  >     * lisp/cedet/semantic/grammar.el (semantic--docstring-format-sym-doc):
>  >     New function.
>  >     (semantic-grammar-eldoc-get-macro-docstring): Adjust.
>  > 
>  > Basically semantic--docstring-format-sym-doc is the old
>  > eldoc-docstring-format-sym-doc.  But I guess the plan is to remove that
>  > eventually, too.  Eldoc got a overhaul recently...
>
>  João, based on this report, do we need some backward-compatibility
>  shim to help 3rd party packages which use this removed function?
>
> From memory, maybe  just bringing back the function as-is should
> do the trick, since eldoc-docstring-format-sym-doc is just a 
> string formatting function, I seem to recall.
>
> I hope this can wait for monday, as I don't have much time
> for emacs devel this weekend.
>
> Ideally though, elpy would rely on the new API, if possible.
> Is Elpy using the new eldoc.el because it's being started
> with Emacs 28 or because it's fetching the package from 
> GNU ELPA?

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.

João


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Bring-back-eldoc-docstring-format-sym-doc-but-obsole.patch --]
[-- Type: text/x-diff, Size: 5035 bytes --]

From a8ac95944ca84ae094b5ae33d00b9966da969cdf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= <joaotavora@gmail.com>
Date: Sun, 26 Jul 2020 11:10:11 +0100
Subject: [PATCH] Bring back eldoc-docstring-format-sym-doc but obsolete it

* lisp/cedet/semantic/grammar.el
(semantic--docstring-format-sym-doc): Call
eldoc-docstring-format-sym-doc.

* lisp/emacs-lisp/eldoc.el (eldoc-docstring-format-sym-doc): Bring
back from dead.
---
 lisp/cedet/semantic/grammar.el | 36 ++-----------------------------
 lisp/emacs-lisp/eldoc.el       | 39 ++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 34 deletions(-)

diff --git a/lisp/cedet/semantic/grammar.el b/lisp/cedet/semantic/grammar.el
index 1ed18339a7..4acaa2fb22 100644
--- a/lisp/cedet/semantic/grammar.el
+++ b/lisp/cedet/semantic/grammar.el
@@ -1664,40 +1664,8 @@ semantic-grammar-syntax-help
 (defvar semantic-grammar-eldoc-last-data (cons nil nil))
 
 (defun semantic--docstring-format-sym-doc (prefix doc &optional face)
-  "Combine PREFIX and DOC, and shorten the result to fit in the echo area.
-
-When PREFIX is a symbol, propertize its symbol name with FACE
-before combining it with DOC.  If FACE is not provided, just
-apply the nil face.
-
-See also: `eldoc-echo-area-use-multiline-p'."
-  ;; Hoisted from old `eldoc-docstring-format-sym-doc'.
-  ;; If the entire line cannot fit in the echo area, the symbol name may be
-  ;; truncated or eliminated entirely from the output to make room for the
-  ;; description.
-  (when (symbolp prefix)
-    (setq prefix (concat (propertize (symbol-name prefix) 'face face) ": ")))
-  (let* ((ea-multi eldoc-echo-area-use-multiline-p)
-         ;; Subtract 1 from window width since emacs will not write
-         ;; any chars to the last column, or in later versions, will
-         ;; cause a wraparound and resize of the echo area.
-         (ea-width (1- (window-width (minibuffer-window))))
-         (strip (- (+ (length prefix)
-                      (length doc))
-                   ea-width)))
-    (cond ((or (<= strip 0)
-               (eq ea-multi t)
-               (and ea-multi (> (length doc) ea-width)))
-           (concat prefix doc))
-          ((> (length doc) ea-width)
-           (substring (format "%s" doc) 0 ea-width))
-          ((>= strip (string-match-p ":? *\\'" prefix))
-           doc)
-          (t
-           ;; Show the end of the partial symbol name, rather
-           ;; than the beginning, since the former is more likely
-           ;; to be unique given package namespace conventions.
-           (concat (substring prefix strip) doc)))))
+  "Call obsolete `eldoc-docstring-format-sym-doc', which see."
+  (eldoc-docstring-format-sym-doc prefix doc face))
 
 (defun semantic-grammar-eldoc-get-macro-docstring (macro expander)
   "Return a one-line docstring for the given grammar MACRO.
diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index fcb104e547..d2d68b30fe 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -809,6 +809,45 @@ eldoc-remove-command-completions
     (apply #'eldoc-remove-command
            (all-completions name eldoc-message-commands))))
 
+(make-obsolete 'eldoc-docstring-format-sym-doc
+               "Use features of `eldoc-documentation-functions' instead"
+               "eldoc-1.1.0")
+
+(defun eldoc-docstring-format-sym-doc (prefix doc &optional face)
+  "Combine PREFIX and DOC, and shorten the result to fit in the echo area.
+
+When PREFIX is a symbol, propertize its symbol name with FACE
+before combining it with DOC.  If FACE is not provided, just
+apply the nil face.
+
+See also: `eldoc-echo-area-use-multiline-p'."
+  ;; If the entire line cannot fit in the echo area, the symbol name may be
+  ;; truncated or eliminated entirely from the output to make room for the
+  ;; description.
+  (when (symbolp prefix)
+    (setq prefix (concat (propertize (symbol-name prefix) 'face face) ": ")))
+  (let* ((ea-multi eldoc-echo-area-use-multiline-p)
+         ;; Subtract 1 from window width since emacs will not write
+         ;; any chars to the last column, or in later versions, will
+         ;; cause a wraparound and resize of the echo area.
+         (ea-width (1- (window-width (minibuffer-window))))
+         (strip (- (+ (length prefix)
+                      (length doc))
+                   ea-width)))
+    (cond ((or (<= strip 0)
+               (eq ea-multi t)
+               (and ea-multi (> (length doc) ea-width)))
+           (concat prefix doc))
+          ((> (length doc) ea-width)
+           (substring (format "%s" doc) 0 ea-width))
+          ((>= strip (string-match-p ":? *\\'" prefix))
+           doc)
+          (t
+           ;; Show the end of the partial symbol name, rather
+           ;; than the beginning, since the former is more likely
+           ;; to be unique given package namespace conventions.
+           (concat (substring prefix strip) doc)))))
+
 \f
 ;; Prime the command list.
 (eldoc-add-command-completions
-- 
2.25.1

Re: eldoc-docstring-format-sym-doc

[Frank Haun]

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

I've pointed to:

  https://lists.gnu.org/archive/html/emacs-devel/2020-07/msg00584.html

Frank

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