master b02c9bc: Improve documentation of new Xref options

[Eli Zaretskii]

branch: master
commit b02c9bccebb47ae83bfcca03d3f97db397861568
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of new Xref options
    
    * lisp/progmodes/xref.el (xref-auto-jump-to-first-definition)
    (xref-auto-jump-to-first-xref): More accurate description in the
    doc strings.
    
    * doc/emacs/maintaining.texi (Looking Up Identifiers)
    (Identifier Search, List Identifiers, Project File Commands): Fix
    the documentation of 'xref-auto-jump-to-first-definition' and
    'xref-auto-jump-to-first-xref' to be more accurate.
    
    * etc/NEWS: More accurate wording of the entry about
    'xref-auto-jump-to-first-definition' and
    'xref-auto-jump-to-first-xref'.
---
 doc/emacs/maintaining.texi | 44 ++++++++++++++++++++++++--------------------
 etc/NEWS                   | 19 ++++++++++++-------
 lisp/progmodes/xref.el     | 13 +++++++++----
 3 files changed, 45 insertions(+), 31 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 5b33c9b..578ef0c 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1747,10 +1747,12 @@ commands (@pxref{Xref Commands}).  When invoked with a 
prefix
 argument, this command additionally prompts for the base directory
 from which to start the search; this allows, for example, to limit the
 search only to project files under a certain subdirectory of the
-project root.
+project root.  The way this command displays the matches is affected
+by the value of @code{xref-auto-jump-to-first-xref} (@pxref{Identifier
+Search}).
 
 @findex project-search
-  @kbd{M-x project-search} is an interactive variant of
+  @kbd{M-x project-search} is an incremental variant of
 @code{project-find-regexp}.  It prompts for a regular expression to
 search in the current project's files, but instead of finding all the
 matches and displaying them, it stops when it finds a match and visits
@@ -2155,20 +2157,11 @@ which these definitions are found.  Selecting one of 
these candidates
 by typing @kbd{@key{RET}} or clicking @kbd{mouse-2} will pop a buffer
 showing the corresponding definition.  If the value of the variable
 @code{xref-auto-jump-to-first-definition} is @code{move}, the first
-candidate is automatically selected, and if it's @code{t} or
-@code{show}, the first candidate is automatically shown.  The default
-value is @code{nil}, which just shows the candidates in the
-@file{*xref*} buffer, but doesn't select any of them.
-
-@vindex xref-auto-jump-to-first-xref
-  If the value of the variable @code{xref-auto-jump-to-first-xref} is
-@code{t}, @emph{all} Xref commands automatically jump to the first
-result.  If the value is @code{show}, the first result is shown, but
-the window showing the @file{*xref*} buffer is left selected.  If the
-value is @code{move}, the first result is selected in the
-@file{*xref*} buffer, but is not shown.  The default value is
-@code{nil}, which just shows the results in the @file{*xref*} buffer,
-but doesn't select any of them.
+of these candidates is automatically selected, and if it's @code{t} or
+@code{show}, the first candidate is automatically shown; @code{t} also
+selects the window showing the first candidate.  The default value is
+@code{nil}, which just shows the candidates in the @file{*xref*}
+buffer, but doesn't select any of them.
 
   When entering the identifier argument to @kbd{M-.}, the usual
 minibuffer completion commands can be used (@pxref{Completion}), with
@@ -2337,6 +2330,16 @@ identifier, showing the file name and the line where the 
identifier is
 referenced.  The XREF mode commands are available in this buffer, see
 @ref{Xref Commands}.
 
+@vindex xref-auto-jump-to-first-xref
+  If the value of the variable @code{xref-auto-jump-to-first-xref} is
+@code{t}, @code{xref-find-references} automatically jumps to the first
+result and selects the window where it is displayed.  If the value is
+@code{show}, the first result is shown, but the window showing the
+@file{*xref*} buffer is left selected.  If the value is @code{move},
+the first result is selected in the @file{*xref*} buffer, but is not
+shown.  The default value is @code{nil}, which just shows the results
+in the @file{*xref*} buffer, but doesn't select any of them.
+
 @findex xref-query-replace-in-results
   @kbd{M-x xref-query-replace-in-results} reads a regexp to match identifier
 names and a replacement string, just like ordinary @kbd{M-x
@@ -2409,6 +2412,8 @@ selected tags table if one is loaded 
(@code{completion-at-point}).
 
 @item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
 Display a list of all known identifiers matching @var{regexp}.
+The way this command displays the matches is affected by the value of
+@code{xref-auto-jump-to-first-xref} (@pxref{Identifier Search}).
 
 @item M-x list-tags @key{RET} @var{file} @key{RET}
 Display a list of the identifiers defined in the program file
@@ -2435,10 +2440,9 @@ for the project to be available.  @xref{Tags Tables}.  
If used
 interactively, the default tag is file name of the current buffer if
 used interactively.
 
-@c Sadly, the new-and-improved Xref feature doesn't provide anything
-@c close to the described below features of the now-obsoleted
-@c tags-apropos.  I'm leaving this here to encourage enhancements to
-@c xref.el.
+@c Sadly, the new-and-improved Xref feature doesn't provide some
+@c of the features of the now-obsoleted tags-apropos.  I'm leaving
+@c this here to encourage enhancements to xref.el.
 @ignore
 @findex tags-apropos
 @vindex tags-apropos-verbose
diff --git a/etc/NEWS b/etc/NEWS
index 38a5749..52a1443 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2309,13 +2309,18 @@ before navigating to the selected location.
 +++
 *** New user options to automatically show the first Xref match.
 The new user option 'xref-auto-jump-to-first-definition' controls the
-behavior of 'xref-find-definitions' and related commands: if it's t or
-'show', the first match is automatically displayed; if it's 'move',
-point in the "*xref*" buffer is automatically moved to the first match
-without displaying it.
-The new user option 'xref-auto-jump-to-first-xref' changes the behavior of
-all Xref commands in the same way as 'xref-auto-jump-to-first-definition'
-affects the "find-definitions" commands.
+behavior of 'xref-find-definitions' and related commands, like
+'xref-find-definitions-other-windo': if it's t or 'show', the first
+match is automatically displayed; if it's 'move', point in the
+"*xref*" buffer is automatically moved to the first match without
+displaying it.
+The new user option 'xref-auto-jump-to-first-xref' changes the
+behavior of Xref commands such as 'xref-find-references',
+'xref-find-apropos', and 'project-find-regexp', which are expected to
+display many match that the user would like to
+visit. 'xref-auto-jump-to-first-xref' changes their behavior muuch in
+the same way as 'xref-auto-jump-to-first-definition' affects the
+"find-definitions" commands.
 
 *** New user options 'xref-search-program' and 'xref-search-program-alist'.
 So far 'grep' and 'ripgrep' are supported.  'ripgrep' seems to offer better
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index d022baaf..f6d88e1 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -420,7 +420,9 @@ elements is negated: these commands will NOT prompt."
   "If t, `xref-find-definitions' always jumps to the first result.
 `show' means to show the first result's location, but keep the
 focus on the Xref buffer's window.
-`move' means to only move point to the first result."
+`move' means to only move point to the first result.
+This variable also affects commands similar to `xref-find-definitions',
+such as `xref-find-definitions-other-window'."
   :type '(choice (const :tag "Jump" t)
                  (const :tag "Show" show)
                  (const :tag "Move point only" move)
@@ -429,13 +431,16 @@ focus on the Xref buffer's window.
   :package-version '(xref . "1.2.0"))
 
 (defcustom xref-auto-jump-to-first-xref nil
-  "If t, xref commands always jump to the first result.
+  "If t, `xref-find-references' always jumps to the first result.
 `show' means to show the first result's location, but keep the
 focus on the Xref buffer's window.
 `move' means to only move point to the first result.
+This variable also affects commands similar to `xref-find-definitions',
+such as `xref-find-references-at-mouse', `xref-find-apropos',
+and `project-find-regexp'.
 
-Please be careful changing this value if you are using Emacs 27
-or earlier: it can break dired-do-find-regexp-and-replace."
+Please be careful when changing the value if you are using Emacs 27
+or earlier: it can break `dired-do-find-regexp-and-replace'."
   :type '(choice (const :tag "Jump" t)
                  (const :tag "Show" show)
                  (const :tag "Move point only" move)