[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Bug-readline] Minor bone to pick regarding the doc for next_history
Re: [Bug-readline] Minor bone to pick regarding the doc for next_history()
Tue, 7 Apr 2015 04:24:49 -0600
Have to respectfully disagree that your rewording addresses the problem with
the original text. IMO the reader's uncertainty as to the value of 'offset'
when the function returns is still present.
Chet Ramey <address@hidden> [2015-04-06 14:17:38 -0400]:
> If the current history offset is not already at the end of the history
> list, move the current history offset forward to the next history entry,
> and return the a pointer to that entry. If there is no next entry, return
> a \fBNULL\fP pointer. If this function returns \fBNULL\fP, the current
> history offset is at the end of the history list.
Seems to me there are two issues, one trivial, one not:
The trivial one is just wordsmithing: The phrase "current history offset" is
used twice yet seems to have two different meanings: The first usage seems to
refer to the value prior to the call, and the second seems to refer to the
value after the function returns. (Or maybe not?) Anyway, let's ignore this,
it's nitpicking, and easily fixed. (Also, "...returns the a pointer...").
The second is important though, about the semantics of the phrase "already
at the end of the history list".
Consider these three pre-call situations, all of which can occur in practice:
(1) offset == history_length-2
(2) offset == history_length-1
(3) offset == history_length
Think about these vis a vis your phrase "already at the end of the history
list" and the meaning the reader may attach to it. It seems to me that (1)
and (3) have no wiggle room for interpretation: Situation (1) cannot reasonably
be interpreted as "already at the end of the history list" and (3) _must_ be
interpreted as "already at the end of the history list". No wiggle room.
Now consider situation (2), and read the first sentence of your text above,
as if you were a first-time reader. Ask yourself: Does the phrase "not already
at the end of the history list" apply to (2)?
If the reader's answer is 'yes' (i.e. 'offset' is "not at the end of the
history list") then your text correctly describes the function's actual
behavior upon return: The value of 'offset' has been incremented and is now
equal to history_length. But if his answer is 'no', then he gets the
wrong idea about the value of 'offset' upon return: He thinks it'll still
be history_length-1, because according to your text it wasn't incremented.
That's the same ambiguity problem as with the original text.
Does a reader have to be obtuse or careless to answer "no"? Not at all, IMO.
After all, in situation (2) 'offset' points to the final _text_ entry in
the list. If he were to call current_history() in this situation, it would
return that final text entry. In other words, in common parlance, the
current_history() function would tell him that the 'offset' pointer is
"currently at the last entry in the history list". It just doesn't seem
unreasonable for a reader to interpret "the pointer is currently at the
last entry in the history list" as synonymous with your phrase "already at
the end of the history list". And if he interprets it that way, he gets
the wrong idea about the value of 'offset' upon return.
The wording that I had suggested
"If the current history offset points to an extant history entry, then
increment it, otherwise leave it as is. If the conditionally incremented
history offset points to an extant history entry, return a pointer
to that entry, otherwise return a \fBNULL\fP pointer."
used the phrase "extant history entry" specifically to avoid ambiguity about
the meaning of "end of the list" and "no next entry". Admittedly the word
"extant" is slightly unusual, but it's not obscure. In view of its definition
("currently existing; not having disappeared") there doesn't seem to be much
room for misinterpretation.