[Emacs-diffs] emacs-26 cd90325: Improve documentation of M-?

[Eli Zaretskii]

branch: emacs-26
commit cd9032532d119b35685dc078b8156023122f6dcd
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of M-?
    
    * doc/emacs/maintaining.texi (Identifier Search):
    * lisp/progmodes/xref.el (xref-find-references): Improve
    documentation of xref-find-references and
    xref-prompt-for-identifier.  (Bug#32389)
---
 doc/emacs/maintaining.texi | 11 ++++++++---
 lisp/progmodes/xref.el     |  6 +++++-
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 9421691..d7d7edd 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1966,9 +1966,14 @@ Restart one of the last 2 commands above, from the 
current location of point.
 
 @kindex M-?
 @findex xref-find-references
-  @kbd{M-?} finds all the references for the identifier at point.  If
-there's no identifier at point, or when invoked with a prefix
-argument, the command prompts for the identifier, with completion.  It
+  @kbd{M-?} finds all the references for the identifier at point,
+prompting for the identifier as needed, with completion.  Depending on
+the current backend (@pxref{Xref}), the command may prompt even if it
+finds a valid identifier at point.  When invoked with a prefix
+argument, it always prompts for the identifier.  (If you want it to
+prompt always, customize the value of the variable
address@hidden to @code{t}; or set it to @code{nil}
+to prompt only if there's no usable identifier at point.)  The command
 then presents the @file{*xref*} buffer with all the references to the
 identifier, showing the file name and the line where the identifier is
 referenced.  The XREF mode commands are available in this buffer, see
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index b0bdd62..e563951 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -866,7 +866,11 @@ buffer where the user can select from the list."
 ;;;###autoload
 (defun xref-find-references (identifier)
   "Find references to the identifier at point.
-With prefix argument, prompt for the identifier."
+This command might prompt for the identifier as needed, perhaps
+offering the symbol at point as the default.
+With prefix argument, or if `xref-prompt-for-identifier' is t,
+always prompt for the identifier.  If `xref-prompt-for-identifier'
+is nil, prompt only if there's no usable symbol at point."
   (interactive (list (xref--read-identifier "Find references of: ")))
   (xref--find-xrefs identifier 'references identifier nil))