bug#35702: xref revert-buffer

[Eli Zaretskii]

> Cc: 35702@debbugs.gnu.org, juri@linkov.net
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 27 May 2019 17:54:21 +0300
> 
> On 26.05.2019 19:44, Eli Zaretskii wrote:
> 
> >> It's akin to asking what values could revert-buffer-function have:
> >> different ones.
> > 
> > Although in theory there could indeed be an infinite number of values,
> > in practice the current actual set is very small, and can be easily
> > described.
> 
> And yet, it's not hugely important to the code that's calling it.

It was important to me.  You prodded me to ask questions and tell you
what made the code reading difficult for me, remember?  Now you are
trying to convince me that it isn't a difficulty, or that I shouldn't
be asking for that?

> So previously, we passed a list of xrefs to xref--show-xrefs. Now we 
> pass a function that returns said list instead. It's a fairly trivial 
> change by itself, so if the previous state of affairs was okay, the new 
> one shouldn't require a lot of new documentation.

You assume that the previous state was okay, which is not a given.
Moreover, you assume that the reader remembers there was a list
before, and can therefore "easily" translate this knowledge to the new
code, instantly understanding that the function now returns the list
that was previously passed as argument.  That's a lot of assumptions.

> > If you want to avoid the (IMO imaginary) danger of
> > implying there could be no other values, you can say explicitly that
> > other values are possible.
> 
> That depends on the level of detail you would like. The minimal level 
> description is in the docstring, and it should be fine for understanding 
> any code that uses FETCHER.

I hope you trust me to have read every bit of comment and doc string I
could possibly find before complaining.

> The general way we describe our code could, of course, be improved, but 
> I don't subscribe to the idea that we can have a general overview of the 
> system no matter where we start reading the code.

See, I was sure I will get a response like that, which was why I
marked what I wrote as <rant>.  If you don't intend to humor requests
for more documentation of the code's workings, then why do you respond
to such rants?  It's a waste of time for both of us, and the result is
known in advance.

I guess I should simply shut up about this next time.  Sorry I wasn't
wiser this time.