Improve documentation of 'xref-find-references-and-replace'

* etc/NEWS: Clarify the 'xref-find-references-and-replace' entry.

* doc/emacs/maintaining.texi (Identifier Search): Document
'xref-find-references-and-replace'.

2 files changed, 10 insertions, 1 deletions

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 9a23f23e0ed..e508e87b8dc 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2321,6 +2321,10 @@ Find all the references for the identifier at point.
 Interactively replace @var{regexp} with @var{replacement} in the names
 of all the identifiers shown in the @file{*xref*} buffer.
 
+@item M-x xref-find-references-and-replace @key{RET} @var{from} @key{RET} @var{to} @key{RET}
+Interactively rename all instances of the identifier @var{from} to the
+new name @var{to}.
+
 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
 Search for @var{regexp} through the files in the selected tags
 table.
@@ -2366,6 +2370,11 @@ files where these identifiers are referenced.  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-?}.
 
+@findex xref-find-references-and-replace
+  @kbd{M-x xref-find-references-and-replace} works similarly to
+@code{xref-query-replace-in-results}, but is more convenient when you
+want to rename a single identifier specified by its name @var{from}.
+
 @findex tags-search
   @kbd{M-x tags-search} reads a regexp using the minibuffer, then
 searches for matches in all the files in the selected tags table, one
diff --git a/etc/NEWS b/etc/NEWS
index 2f0fe005556..ea9ba49892f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -598,7 +598,7 @@ It is bound to 'C-M-,' and jumps to the location where 'xref-go-back'
 called without prefix argument, to make the most common case faster:
 replacing entire matches.
 
-*** New command 'xref-find-references-and-replace'.
+*** New command 'xref-find-references-and-replace' to rename one identifier.
 
 ** File notifications