Re: xref rocks!

[Dmitry Gutov]

On 04/27/2016 06:35 AM, Robert Weiner wrote:

> Yes, that is helpful.  So why not include a wrapper for the API of
> something like:
>    (xref-get-definitions "car")

That seems unnecessary. And you yourself complained about the wrappers 
that don't do much.

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

Hmm, I suppose we could eliminate xref--find-definitions, but then each 
of xref-find-definitions-other-window, 
xref-find-definitions-other-window and xref-find-definitions-other-frame 
will have to call xref--find-xrefs with a bit more complex sets of 
arguments. An extra indirection don't seem a big enough problem to 
justify this.

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

Just like you've used it before that?

> i.e. what commands are available and what parameters do they require, or

To see the available commands type `M-x xref- TAB'. If you mean 
functions, then `C-h f xref- TAB'. Although yes, a friendly explanation 
along the lines of "do this and that go that that" should have its place 
in the manual.

> for programmers, what do the resulting API calls look like?

Not sure I understand. What does look like? The implementations of the 
generic methods? They return lists of xref values.

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

That sounds like manual material. I think writing it is premature at 
this point, but sure, we should have it eventually.