Subject: bug#32389: closed (Re: bug#32389: Default behaviour of xref-find-references is inconsistent with the documentation)

From: [email-masked] (GNU bug Tracking System)
Date: Tue, 07 Aug 2018 16:21:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
32389: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=32389
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#32389: Default behaviour of xref-find-references is inconsistent with the documentation
From: Eli Zaretskii <[email-masked]>
To: Shitikanth <[email-masked]>
Cc: [email-masked]
Date: Tue, 07 Aug 2018 19:20:23 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Shitikanth <[email-masked]>
> 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.

Subject: Default behaviour of xref-find-references is inconsistent with the documentation
From: Shitikanth <[email-masked]>
To: [email-masked]
Date: Tue, 7 Aug 2018 14:25:46 +0530
List-Id: <debbugs-submit.debbugs.gnu.org>

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.