Re: eldoc-docstring-format-sym-doc

[João Távora]

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

>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)))))
+
 
 ;; Prime the command list.
 (eldoc-add-command-completions
-- 
2.25.1