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 <[email protected]> [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. _______________________________________________ Bug-readline mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-readline
