RFR: 8326096: Deprecate getTotalIn, getTotalOut methods of java.util.zip.Inflater, java.util.zip.Deflater [v4]

[Eirik Bjørsnøs]

On Sun, 25 Feb 2024 15:19:59 GMT, Alan Bateman <alanb at 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