bug#35702: xref revert-buffer

[Dmitry Gutov]

On 24.05.2019 22:35, Eli Zaretskii wrote:

> > First: my point is, it's possible that it *will* always work wherever
> > you are able to invoke it with 'g'. The Xref buffers where it wouldn't
> > work wouldn't bind 'g'.
>
> Sorry, I don't understand what you are saying here.  If some XREF
> buffers won't have the 'g' bound to a command, why do we have it bound
> now, and why do we have an error message when the command cannot be
> used?

Because nobody has written a better alternative UI for 
xref-find-definitions specifically yet. But when someone(tm) does, it'll 
likely have a different keymap.

Anyway, never mind that for now.

> > Think forward: if we expose the Xref UI as a library for other packages
> > in the future (and we probably will), should we allow some of them to
> > opt out of revert-ability (for simplicity, let's say), or not?
>
> In general, I consider such changes a bad idea: XREF is a mode, and a
> mode should be consistent across all its users.

Fair enough.

> > > Why is it a problem to say that XREF buffers created by
> > > xref-find-definitions currently don't support 'g'?
> >
> > Because it feels ad-hoc and kinda weird.
>
> Are you going to add support for it any time soon?

Apparently I am!

> > Hmm. So it's something you would really find useful?
>
> Yes.

OK.

> > To be clear, though, we *can* add support for reverting to
> > xref-find-definitions as well, if you want. Just at the cost of a
> > certain increase of complexity, see if you like the patch.
> > xref-find-defitions-revertable.diff is attached.
>
> Doesn't look to me like it adds any significant complexity.

OK, I'll install it, if only to make the documentation simpler. That's 
something I hadn't really considered in advance.

> > Just to be clear: I'm referring to two of the three entries I've showed
> > in the previous email mentioning "search-type Xref commands".
>
> Why is that "duplication"?  using the same terminology is a Good
> Thing, as it allows the reader easier understanding what is being
> discussed.

I was thinking it would be better to coin a common term that separates 
"other" Xref commands from xref-find-definitions, so we don't have to 
enumerate them later.

This distinction is also important, for instance, to make the purposes 
of xref-show-xrefs-function and xref-show-definitions-function clear in 
their docstrings.

> > Would a docstring saying "Function that returns a list of xrefs
> > containing the search results" change things?
>
> I meant a comment that would explain how things worked and in what
> scenarios.

Would you be surprised to hear that I don't even know where to begin?

When doing something for xref.el or project.el, lately I spend quite a 
bit of time thinking how to make the concepts more transparent, and very 
little time implementing them. So I currently feel that the ideas are 
simple (meaning, there are no behaviors that require particular extra 
commentary), and the implementations are maybe too simplistic.

There are much more difficult things in this package, e.g. window 
management.

> > Where the fetcher is created is not to hard to find, I think (only a few
> > local variables with that name).
>
> Finding the places where it is defined is easy enough; understanding
> the semantics of that isn't.  The code is obfuscated by using generic
> names like "method", and has no comments explaining what is going on
> in plain English.

method uses the cl-generic infrastructure (which might be 
under-documented, though happily though no fault of my own), but you 
don't need to understand it to see what's going on with fetcher.

(xref-backend-definitions backend id) returns a list of definitions. 
That's all what's necessary to know here.

> > It's not like I'm against those, but it might take a different person to
> > identify the places that need to be commented.
>
> That different person will not know enough about the code to add
> useful comments.  Not unless they invest the effort to study and
> understand it.

They could ask specific questions. It's harder to answer a question like 
"explain all this stuff to me".