On Sun, 25 Feb 2024 15:19:59 GMT, Alan Bateman <al...@openjdk.org> wrote:
> For the class description then it might be simpler to reduce the new text
> down to one sentence, e.g.
@AlanBateman Thanks for the condensed text, that's indeed much better! I've
pushed your suggestion, only adding a link around Integer.MAX_VALUE for
consistency with the deprecation text.
I'm wondering if the somewhat tedious "number of compressed bytes input so far"
could be further simplified. Besides being a long repetition from the leading
sentence, when used in this sentence, we actually mean to refer to the "actual,
correct, real value", potentially different from the return value. (We mean the
value returned by getBytesRead(), but we don't say so). Additionally, some
amount of brainwork is required to parse what the "it" refers to. (It's pretty
clear when you think about it, but you need to think :-)
Would it be better to refer to the number returned by getBytesRead() instead?
Something like this:
* This method returns the equivalent of {@code (int) getBytesRead()}
* and therefore cannot return the correct value when the number returned
by
* {@link #getBytesRead()} is greater than {@link Integer#MAX_VALUE}.
For comparison, here is the current text:
* This method returns the equivalent of {@code (int) getBytesRead()}
* and therefore cannot return the correct number of compressed bytes
* input so far when it is greater than {@link Integer#MAX_VALUE}.
Do you think this is an improvement? (I'm also fine with the current text)
-------------
PR Comment: https://git.openjdk.org/jdk/pull/17919#issuecomment-1964358746
