bug#32389: Default behaviour of xref-find-references is inconsistent with the documentation

[Eli Zaretskii <eliz@gnu.org>]

> From: Shitikanth <shitikanth1@gmail.com>
> Date: Tue, 7 Aug 2018 14:25:46 +0530
> 
> The function documentation of xref-find-references says:
> 
>     Find references to the identifier at point. With prefix argument, prompt for
>     the identifier.
> 
> The Emacs manual (Node: Identifier Search) says:
> 
>     ‘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.
> 
> Inconsistent to both, the actual behaviour of xref-find-references and M-? is to
> *always* prompt for the identifier from the user (irrespective of whether it is
> invoked with or without the prefix-arg).

That's inaccurate: the actual behavior depends on the Xref backend,
and cannot be predicted in advance for every backend.  If the
backend-specific xref-backend-identifier-at-point method returns a
non-nil identifier, the command will not prompt.

However, the current documentation is also clearly inaccurate, so I
made it more so.

> The only way to get the documented
> behaviour is by customizing xref-prompt-for-identifier, and there is no way of
> discovering this without reading the source code.

Good point, I added a reference to the variable to the documentation
of the command.

With that, I'm closing the bug.  Thanks for bringing this to our
attention.