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

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

[Shitikanth]

[-- Attachment #1: Type: text/plain, Size: 835 bytes --]

Related to bug#29619.

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). 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.

[-- Attachment #2: Type: text/html, Size: 2271 bytes --]

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

[Eli Zaretskii]

> 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.

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

[Eli Zaretskii]

> From: Shitikanth <shitikanth1@gmail.com>
> Date: Tue, 7 Aug 2018 23:45:42 +0530
> 
> I, for one, feel that this has become more complex than it needs to be. Since C-u M-?
> gives the option to force a prompt anyway, the default behaviour should be for M-?
> to not show a prompt unless needed (that is if the xref-backend is not able to find
> an identifier at point). 

You are arguing for a change in the default behavior, something that
we don't usually do based on a single opinion.  You can always
customize xref-prompt-for-identifier on your system to get this
behavior for yourself; changing that for everyone requires some kind
of user poll, at least.