[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: |
Sun, 26 Jul 2020 11:16:31 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) |
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