GNU bug report logs - #32389
Default behaviour of xref-find-references is inconsistent with the documentation

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 32389 in the body.
You can then email your comments to 32389 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Shitikanth <shitikanth1 <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Default behaviour of xref-find-references is inconsistent with the
 documentation
Date: Tue, 7 Aug 2018 14:25:46 +0530

[Message part 1 (text/plain, inline)]

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.

[Message part 2 (text/html, inline)]

Message #10 received at 32389-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Shitikanth <shitikanth1 <at> gmail.com>
Cc: 32389-done <at> debbugs.gnu.org
Subject: Re: bug#32389: Default behaviour of xref-find-references is
 inconsistent with the documentation
Date: Tue, 07 Aug 2018 19:20:23 +0300

> From: Shitikanth <shitikanth1 <at> 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.

Message #13 received at 32389 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Shitikanth <shitikanth1 <at> gmail.com>
Cc: 32389 <at> debbugs.gnu.org
Subject: Re: bug#32389: Default behaviour of xref-find-references is
 inconsistent with the documentation
Date: Tue, 07 Aug 2018 21:26:40 +0300

> From: Shitikanth <shitikanth1 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.