[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 8c38345: Rename and document the built-in xref-show-definitions-f
From: |
Dmitry Gutov |
Subject: |
master 8c38345: Rename and document the built-in xref-show-definitions-function's |
Date: |
Sun, 27 Dec 2020 19:30:37 -0500 (EST) |
branch: master
commit 8c383456291185b029b469061338b5b797a49747
Author: Dmitry Gutov <dgutov@yandex.ru>
Commit: Dmitry Gutov <dgutov@yandex.ru>
Rename and document the built-in xref-show-definitions-function's
* lisp/progmodes/xref.el (xref-show-definitions-buffer): Rename
from 'xref--show-defs-buffer'.
(xref-show-definitions-buffer-at-bottom): Rename from
'xref--show-defs-buffer-at-bottom'.
---
etc/NEWS | 8 ++++++++
lisp/progmodes/xref.el | 47 ++++++++++++++++++++++++++++++++++++++---------
2 files changed, 46 insertions(+), 9 deletions(-)
diff --git a/etc/NEWS b/etc/NEWS
index 328c666..1319310 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1293,6 +1293,14 @@ searches.
These commands are bound respectively to 'P' and 'N', and navigate to
the first item of the previous or next group in the "*xref*" buffer.
+*** New alternative value for 'xref-show-definitions-function':
+'xref-show-definitions-completing-read'.
+
+*** The two existing alternatives for 'xref-show-definitions-function'
+have been renamed to have "proper" public names and documented
+('xref-show-definitions-buffer' and
+'xref-show-definitions-buffer-at-bottom').
+
** json.el
---
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 181f94b..b8a5d48 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -941,7 +941,10 @@ Return an alist of the form ((FILENAME . (XREF ...)) ...)."
'face 'error))))
(goto-char (point-min)))))
-(defun xref--show-defs-buffer (fetcher alist)
+(defun xref-show-definitions-buffer (fetcher alist)
+ "Show the definitions list in a regular window.
+
+When only one definition found, jump to it right away instead."
(let ((xrefs (funcall fetcher)))
(cond
((not (cdr xrefs))
@@ -952,8 +955,12 @@ Return an alist of the form ((FILENAME . (XREF ...)) ...)."
(cons (cons 'fetched-xrefs xrefs)
alist))))))
-(defun xref--show-defs-buffer-at-bottom (fetcher alist)
- "Show definitions list in a window at the bottom.
+(define-obsolete-function-alias
+ 'xref--show-defs-buffer #'xref-show-definitions-buffer "28.1")
+
+(defun xref-show-definitions-buffer-at-bottom (fetcher alist)
+ "Show the definitions list in a window at the bottom.
+
When there is more than one definition, split the selected window
and show the list in a small window at the bottom. And use a
local keymap that binds `RET' to `xref-quit-and-goto-xref'."
@@ -970,7 +977,14 @@ local keymap that binds `RET' to
`xref-quit-and-goto-xref'."
'(display-buffer-in-direction . ((direction . below))))
(current-buffer))))))
-(defun xref--show-defs-minibuffer (fetcher alist)
+(define-obsolete-function-alias
+ 'xref--show-defs-buffer-at-bottom #'xref-show-definitions-buffer-at-bottom)
+
+(defun xref-show-definitions-completing-read (fetcher alist)
+ "Let the user choose the target definition with completion.
+
+When there is more than one definition, let the user choose
+between them by typing in the minibuffer with completion."
(let* ((xrefs (funcall fetcher))
(xref-alist (xref--analyze xrefs))
xref-alist-with-line-info
@@ -1010,6 +1024,10 @@ local keymap that binds `RET' to
`xref-quit-and-goto-xref'."
(xref-pop-to-location xref (assoc-default 'display-action alist))))
+;; TODO: Can delete this alias before Emacs 28's release.
+(define-obsolete-function-alias
+ 'xref--show-defs-minibuffer #'xref-show-definitions-completing-read "28.1")
+
(defcustom xref-show-xrefs-function 'xref--show-xref-buffer
"Function to display a list of search results.
@@ -1030,11 +1048,22 @@ displayed. The possible values are nil, `window'
meaning the
other window, or `frame' meaning the other frame."
:type 'function)
-(defcustom xref-show-definitions-function 'xref--show-defs-buffer
- "Function to display a list of definitions.
-
-Accepts the same arguments as `xref-show-xrefs-function'."
- :type 'function)
+(defcustom xref-show-definitions-function 'xref-show-definitions-buffer
+ "Function to handle the definition search results.
+
+Accepts the same arguments as `xref-show-xrefs-function'.
+
+Generally, it is expected to jump to the definition if there's
+only one, and otherwise provide some way to choose among the
+definitions."
+ :type '(choice
+ (const :tag "Show a regular list of locations"
+ xref-show-definitions-buffer)
+ (const :tag "Show a \"transient\" list at the bottom of the window"
+ xref-show-definitions-buffer-at-bottom)
+ (const :tag "Choose the definition with completion"
+ xref-show-definitions-completing-read)
+ (function :tag "Custom function")))
(defvar xref--read-identifier-history nil)
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master 8c38345: Rename and document the built-in xref-show-definitions-function's,
Dmitry Gutov <=