Re: xref rocks!

[Robert Weiner]

On Tue, Apr 26, 2016 at 4:41 PM, Dmitry Gutov <address@hidden> wrote:

On 04/26/2016 08:12 PM, Robert Weiner wrote:

One thing that would help would be better
separation between finding xrefs (which should just return lists of
them) and displaying xrefs.  For example, I went looking for a generic
xref equivalent to find-tag-noselect and the only thing I found was
something specific to elisp tags.

 

Are you looking for

   (xref-backend-definitions (xref-find-backend) "car")

Yes, that is helpful.  So why not include a wrapper for the API of something like:

   (xref-get-definitions "car")

Also, there seem to be many functions that just call a single other
functions, creating a deeply nested tree of calls.  Is there a way to
simplify that?

Could you give an example?

xref-find-definitions calls only xref--find-definitions which calls

only xref--find-xrefs which essentially calls only xref--show-xrefs. 

I also see that about a year ago there was a call for documenting
xref.el.  Has any progress been made on that?  Even though things will
change, writing the documentation will give you a base that you can
adapt as the library evolves and will help people to provide further
feedback.

There is an introduction in Commentary at the top of xref.el. You can read it, among other ways, using `M-x describe-package RET xref RET'.

I have read it.  It certainly points to many places in the package and in the backend implementations to look for more documentation but doesn't give a sense of how to use the package after defining a backend, i.e. what commands are available and what parameters do they require, or for programmers, what do the resulting API calls look like?  Including a simple sample backend, much simpler than referencing the existing backends, would also help a lot to show the minimum involved in creating a backend.  Think of someone who knows Elisp and Emacs but knows nothing about xrefs.  Can you tell them 1. how to utilize existing backends and 2. how to create a backend in some detail.

Just some thoughts.

Bob