On Tue, 24 Mar 2026 12:05:07 GMT, Eirik Bjørsnøs <[email protected]> wrote:
>> src/java.base/share/classes/java/util/zip/ZipOutputStream.java line 146:
>>
>>> 144: *
>>> 145: * @param comment the comment string. Passing {@code null} or
>>> an empty string
>>> 146: * will result in the output having no ZIP file
>>> comment
>>
>> It might be better to add to the method description, e.g. "If {@code
>> comment} is the empty string or {@code null} then ..." so that the comment
>> parameter has single sentence, e.g. "the comment string, or an empty string
>> or null for no comment".
>
> Thanks, I think it makes sense to lift this note into the method description
> and just leave the abosulute minimum, for-reference note in the parameter
> decription. See a891743.
No objection to the current text in this PR. It's OK to go ahead with this form.
However, I wasn't thinking of specifying the behaviour of empty value for the
`comment`, because there's nothing special we do with empty vs non-empty
comment string. `null` for comment is special because this method handles it
differently compared to the class level javadoc. So I was leaning towards:
/**
* Sets the ZIP file comment. Passing {@code null} for {@code comment} will
result in
* the ZIP file having no comment.
*
* @param comment the comment string, can be {@code null}
* @throws IllegalArgumentException if the length of the specified
* ZIP file comment is greater than 0xFFFF bytes or if the
* {@code comment} contains characters that cannot be mapped
* by the {@code Charset} of this {@code ZipOutputStream}
*/
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/30338#discussion_r2981134383
