bug#35702: xref revert-buffer

[Eli Zaretskii <eliz@gnu.org>]

> Cc: 35702@debbugs.gnu.org, juri@linkov.net
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Fri, 24 May 2019 23:51:58 +0300
> 
> >> 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.

I'm fine with coming up with some classification of these commands.
But I think the classification should be in the manual, not in NEWS.

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

Yes.

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

I didn't mean to imply that the stuff we were discussing is the only
one that is painful to decipher.

Thanks.