bug#22692: docstring for xref-find-definitions

[Mike Kupfer]

Eli Zaretskii wrote:

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

Okay.  Is there an easy way for the user to tell which backend is in
use?  If there is, then maybe the docstring could say something general
and then note that the user could also check the backend's
documentation.

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

Not that I know of, but I don't know much about Emacs's documentation
infrastructure.

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

Yes, I think that would be an improvement.  Thanks.

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

Interesting.  I use M-. a lot, and I never noticed this.  I suppose it's
because I know I'm going to type in the name that I'm looking for, so I
ignore the default.

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

Okay.  I'll add this to my spare-time projects list.

thanks,
mike