master 8c38345: Rename and document the built-in xref-show-definitions-function's

[Dmitry Gutov]

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)