xref rocks!

xref rocks!

[Nicolas Petton]

[-- Attachment #1: Type: text/plain, Size: 302 bytes --]

Hi guys,

I just want to say that xref is IMO a big step forward, it really rocks!

Its UI is pleasant to use and it's very easily extensible (I added a
backend with just a few methods).

If all ref tools could move to using xref in the future, we'd have a
very consistent UI for jumping around!

Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

Re: xref rocks!

[Dmitry Gutov]

Hey Nicolas,

On 04/25/2016 02:35 PM, Nicolas Petton wrote:

> I just want to say that xref is IMO a big step forward, it really rocks!
>
> Its UI is pleasant to use and it's very easily extensible (I added a
> backend with just a few methods).

I'm glad you like it, but please note that the API is not yet stable. So 
you may have to bump the xref-js2 dependency to emacs-26 sometime during 
it development cycle.

> If all ref tools could move to using xref in the future, we'd have a
> very consistent UI for jumping around!

That would be nice, but it has a bunch of missing spots.

Off the top of my head:

- You can't repeat searches with `g'.
- The n/p commands end up changing the window configuration with no 
reliable way to undo those changes, aside from Winner (and even it won't 
help undo some changes). Not sure what to do about it.
- The situation with "rename refactoring" is a bit uncertain. Right now 
we have xref-quory-replace-in-results, which uses query-replace. I'm not 
sure it's beneficial to keep using it (or even something similar) in the 
long run, and I'm not even sure that a list of xrefs is a good data 
format to base refactorings on. Either we'll have to extend it to more 
"abstract" xrefs (like ones corresponding to files, for renames), or 
introduce a separate data format, and a separate API to feed to the 
refactoring UI.

So I want to see the potential authors evaluate xref and file all kinds 
of feature requests and bug requests, so that we end up stabilizing the 
best possible API we can.

Re: xref rocks!

[Nicolas Petton]

[-- Attachment #1: Type: text/plain, Size: 571 bytes --]

Dmitry Gutov <dgutov@yandex.ru> writes:


> I'm glad you like it, but please note that the API is not yet stable. So 
> you may have to bump the xref-js2 dependency to emacs-26 sometime during 
> it development cycle.

Yeah, I'm aware of that, but I'm fine with it.

>> If all ref tools could move to using xref in the future, we'd have a
>> very consistent UI for jumping around!
>
> That would be nice, but it has a bunch of missing spots.
>
> Off the top of my head:
>
> - You can't repeat searches with `g'.

Indeed, that's a bit annoying.

Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

Re: xref rocks!

[John Wiegley]

>>>>> Nicolas Petton <nicolas@petton.fr> writes:

> I just want to say that xref is IMO a big step forward, it really rocks!

> Its UI is pleasant to use and it's very easily extensible (I added a backend
> with just a few methods).

> If all ref tools could move to using xref in the future, we'd have a very
> consistent UI for jumping around!

This is really great to hear. Kudos to Dmitry.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: xref rocks!

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 982 bytes --]

Hi Dmitry:

Thanks for your work on xref.el.  I agree that the API could use some work
and it will be better.  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.  Shouldn't there be something like
xref-find-definitions that only returns a list of definitions and does not
display them?

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?

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.

Just some thoughts.

Bob

[-- Attachment #2: Type: text/html, Size: 1140 bytes --]

Re: xref rocks!

[Dmitry Gutov]

On 04/26/2016 05:49 PM, John Wiegley wrote:

> This is really great to hear. Kudos to Dmitry.

Thanks. But let's not forget Helmut Eller who provided the initial 
implementation (which I happily butchered :)), and Jorgen Schaefer who 
provided a competing proposal, some pieces of which also made it in.

Re: xref rocks!

[Dmitry Gutov]

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.

find-tag-noselect returns a target buffer, which doesn't seem very relevant.

Are you looking for

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

?

> Shouldn't there be something like
> xref-find-definitions that only returns a list of definitions and does
> not display them?

If you mean returns a list of xrefs, see above.

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

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

And, of course, see the docstrings. (info "(elisp) Generic Functions") 
might also be relevant.

If some things remain unclear, please go ahead and file documentation 
bugs, as long as they are more specific than "Write a manual".

Thanks in advance,
Dmitry.

Re: xref rocks!

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 2126 bytes --]

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

[-- Attachment #2: Type: text/html, Size: 3894 bytes --]

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.

Re: xref rocks!

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 124 bytes --]

I think we have covered this topic enough.  Thanks for the feedback.  I
will look forward to the manual at some point.

Bob

[-- Attachment #2: Type: text/html, Size: 187 bytes --]