On Tue, 14 Jan 2025 06:35:04 GMT, Alan Bateman <al...@openjdk.org> wrote:
>> Jaikiran Pai has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> fix javadoc tag ordering - "@throws" after "@return"
>
> src/java.base/share/classes/java/util/zip/Deflater.java line 52:
>
>> 50: * <p>
>> 51: * This class deflates sequences of bytes into ZLIB compressed data
>> format.
>> 52: * The input byte sequence is provided in either byte array or {@link
>> ByteBuffer},
>
> We should probably fix this sentence to say "in either a byte array or ...".
Fixed.
> src/java.base/share/classes/java/util/zip/Deflater.java line 60:
>
>> 58: * {@code Deflater} by calling either the {@link #end()} or the {@link
>> #close()} method.
>> 59: * After the {@code Deflater} has been closed, subsequent calls to
>> several methods
>> 60: * of the {@code Deflater} will throw an {@link IllegalStateException}.
>
> This paragraph uses the definite article but there isn't a specific Deflater
> to speak of, and it's not a singleton. The first sentence of this paragraph
> might be better if re-worded "To release the resources used a Deflater, an
> application must close it by invoking its end() or close() method".
I have reworded the sentence to follow your input. Addtionally, I've removed
the second sentence, since as you note, relevant methods on the
Inflater/Deflater (as part of this PR) already have been updated to state that
they throw an `IllegalStateException` if the Inflater/Deflater is already
closed.
> src/java.base/share/classes/java/util/zip/Deflater.java line 892:
>
>> 890: * and discards any unprocessed input.
>> 891: * <p>
>> 892: * If this method is invoked multiple times, the second and
>> subsequent calls do nothing.
>
> I think this could be clearer if you replace this sentence with "If the
> Deflater is already closed then invoking this method has no effect."
Done.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/19675#discussion_r1914455153
PR Review Comment: https://git.openjdk.org/jdk/pull/19675#discussion_r1914457795
PR Review Comment: https://git.openjdk.org/jdk/pull/19675#discussion_r1914458103
