On Tue, Apr 26, 2016 at 4:41 PM, Dmitry Gutov <dgutov@yandex.ru> 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