bug#35702: xref revert-buffer

[Dmitry Gutov <dgutov@yandex.ru>]

On 27.05.2019 19:31, Eli Zaretskii wrote:

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

I'm sorry to disappoint. I'm sure you understand that there are question 
I can answer but I'd have hard time converting into code comments.

Here are the kinds of questions I was hoping for:

* What does this function/variable do, or what is it for?

These can translate into [improvements for] docstrings or into top 
Commentary.

* Given the stated purpose of <function> why does it implement it *this 
particular way*?

These can translate into inline comments.

As such, I can answer your question (probably already did), but since 
IMO they are not about xref--fetcher or xref--show-defs, I can't put the 
answers into nearby comments.

So instead I ended up thinking of a few questions along these lines and 
asking them myself, hence the resulting commit that added some more 
documentation.

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

Hopefully the new docstrings will make understanding all that easier anyway.

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

Well, there was some extra documentation added in the meantime, and I'm 
not sure how you feel about it.

>> 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?
I did suggest some other places where new commentary can go.

Maybe you could propose something else as well, now that I've tried to 
explain why your previous suggestion is hard for me to do. If I 
interpreted it correctly, at least.