RFR: 8303923: ZipOutStream::putEntry should include an apiNote to indicate that the STORED compression method should be used when writing directory entries [v2]

[Eirik Bjorsnos]

On Sun, 19 Mar 2023 14:19:10 GMT, Eirik Bjorsnos <duke at openjdk.org> wrote:

>> src/java.base/share/classes/java/util/zip/ZipOutputStream.java line 198:
>> 
>>> 196:      *
>>> 197:      * {@snippet lang="java" :
>>> 198:      *     ZipEntry e = ...;
>> 
>> Please make this an actual value as the snippet should be valid code
>
> I initially used a directory as an example: `ZipEntry e = new ZipEntry("dir/")`, but then @AlanBateman  suggested to make it more generic:
> 
> https://mail.openjdk.org/pipermail/core-libs-dev/2023-March/101686.html
> 
>> For the note then you might want to change it to "ZipEntry e = ..." because the reader see the trailing slash after dir so it is obviously a directory. 
> 
> I agree valid code would be preferrable. Not sure how to make it valid though, since the `isDirectory` part suggests the  path is unknown. Could an undefined local variable work?
> 
> 
> ZipEntry e = new ZipEntry(name);
> 
> 
> Or perhaps with a comment:
> 
> 
> ZipEntry e = new ZipEntry(name); // name could be a file or directory

I opted for `ZipEntry e = new ZipEntry(entryName)` for now.

-------------

PR: https://git.openjdk.org/jdk/pull/12899