bug#22692: docstring for xref-find-definitions

[Eli Zaretskii]

> From: Mike Kupfer <m.kupfer@acm.org>
> Date: Wed, 17 Feb 2016 19:45:21 -0800
> 
> Based on the behavior that I observe (using "emacs -Q" to visit
> src/frame.c), the docstring for xref-find-definitions would be more
> accurate if the first paragraph were replaced by
> 
>   Find the definition of the identifier at point.
>   If there is no identifier at point, use an identifier (or numeric
>   literal) near point on the same line.

We cannot be this specific, not as long as the doc string is literal
text defined as part of 'defun'.  The exact definition of what is "the
identifier at point" depends on the xref backend set up by the major
mode.  That definition could be very smart or it could be less smart.
The command doesn't know.

If we want to be accurate here, we will need to come up with a way for
the back-end to supply its definition, and incorporate that in the doc
string that is created dynamically.  Do we have infrastructure for
that?

Failing that, the only band-aid I can offer is something like

  Find the definition of the identifier at or near point.

If you think it's better, we can make that change now.

> Trying to look up the definition for a numeric literal strikes me as
> odd, but that's the behavior I'm seeing.

Did you use M-. in Emacs 24 and before?  Because that's exactly what
it did in this case, it would say this in the echo area:

  Find tag (default 1):

The reason is that this is what etags.el does when asked to find "the
identifier at or near point".  Patches to make it smarter are welcome.
(The relevant function is find-tag-default-bounds.)

Thanks.