master e016e60a04 1/2: ; Clarify correct use of 'xref-query-replace-in-results'

[Eli Zaretskii]

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

    ; Clarify correct use of 'xref-query-replace-in-results'
    
    * lisp/progmodes/xref.el (xref--query-replace-1): Improve the
    user-error message.
    (xref-query-replace-in-results): Clarify restrictions in the doc
    string.
    
    * doc/emacs/maintaining.texi (Xref Commands, Identifier Search):
    Clarify the correct usage of 'xref-query-replace-in-results'.
---
 doc/emacs/maintaining.texi | 19 ++++++++++++-------
 lisp/progmodes/xref.el     | 18 ++++++++++++------
 2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 6857e67def..671d4dd422 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2302,7 +2302,9 @@ Display the reference on the current line in the other 
window
 @item r @var{pattern} @key{RET} @var{replacement} @key{RET}
 Perform interactive query-replace on references that match
 @var{pattern} (@code{xref-query-replace-in-results}), replacing
-the match with @var{replacement}.  @xref{Identifier Search}.
+the match with @var{replacement}.  This command can only be used in
+@file{*xref*} buffers that show all the matches for an identifier in
+all the relevant files.  @xref{Identifier Search}.
 
 @item g
 @findex xref-revert-buffer
@@ -2336,7 +2338,8 @@ them.
 @item M-?
 Find all the references for the identifier at point.
 
-@item M-x xref-query-replace-in-results @key{RET} @var{replacement} @key{RET}
+@item r@r{, Xref command}
+@itemx M-x xref-query-replace-in-results @key{RET} @var{replacement} @key{RET}
 @itemx C-u M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} 
@var{replacement} @key{RET}
 Interactively replace @var{regexp} with @var{replacement} in the names
 of all the identifiers shown in the @file{*xref*} buffer.
@@ -2382,16 +2385,18 @@ 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 @var{replacement}
+  @kbd{r} (@code{xref-query-replace-in-results}) reads a @var{replacement}
 string, just like ordinary @kbd{M-x query-replace-regexp}.  It then
 renames the identifiers shown in the @file{*xref*} buffer in all the
 places in all the files where these identifiers are referenced, such
 that their new name is @var{replacement}.  This is useful when you
 rename your identifiers as part of refactoring.  This command should
-be invoked in the @file{*xref*} buffer generated by @kbd{M-?}.  With a
-prefix argument, the command also prompts for a regexp to match
-identifier names, and renames that regexp in the names of the matching
-identifiers with @var{replacement}.
+be invoked in the @file{*xref*} buffer generated by @kbd{M-?}.  By
+default, the command replaces the entire name of each identifier with
+@var{replacement}, but if invoked with a prefix argument, the command
+prompts for a regexp to match identifier names, and replaces only the
+matches of that regexp in the names of the identifiers with
+@var{replacement}.
 
 @findex xref-find-references-and-replace
   @kbd{M-x xref-find-references-and-replace} works similarly to
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index ac04b64ce5..47b4b3d15c 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -751,17 +751,22 @@ quit the *xref* buffer."
 (defun xref-query-replace-in-results (from to)
   "Perform interactive replacement of FROM with TO in all displayed xrefs.
 
-This command interactively replaces FROM with TO in the names of the
+This function interactively replaces FROM with TO in the names of the
 references displayed in the current *xref* buffer.
 
-When called interactively, it uses '.*' as FROM, which means
-replace the whole name.  Unless called with prefix argument, in
-which case the user is prompted for both FROM and TO.
+When called interactively, it uses '.*' as FROM, which means replace
+the whole name, and prompts the user for TO.
+If invoked with prefix argument, it prompts the user for both FROM and TO.
 
 As each match is found, the user must type a character saying
 what to do with it.  Type SPC or `y' to replace the match,
 DEL or `n' to skip and go to the next match.  For more directions,
-type \\[help-command] at that time."
+type \\[help-command] at that time.
+
+Note that this function cannot be used in *xref* buffers that show
+a partial list of all references, such as the *xref* buffer created
+by \\[xref-find-definitions] and its variants, since those list only
+some of the references to the identifiers."
   (interactive
    (let* ((fr
            (if current-prefix-arg
@@ -891,7 +896,8 @@ ITEMS is an xref item which " ; FIXME: Expand documentation.
       (setq pairs (cdr buf-pairs))
       (setq continue
             (perform-replace from to t t nil nil multi-query-replace-map)))
-    (unless did-it-once (user-error "No suitable matches here"))
+    (unless did-it-once
+      (user-error "Cannot use subset of matches for global renaming"))
     (when (and continue (not buf-pairs))
       (message "All results processed"))))