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

[Eirik Bjorsnos]

ZipOutputStream currently writes directory entries using the DEFLATED compression method. This does not strictly comply with the APPNOTE.TXT specification and is also about 10x slower than using the STORED compression method.

Because of these concerns, `ZipOutputStream.putNextEntry` should be updated with an `@apiNote` recommending
the use of the STORED compression method for directory entries.

Suggested CSR in the first comment.

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

Commit messages:
 - For consistency with other Javadocs, use 'CRC-32' instead of 'crc' when referring to the checksum
 - Generalize the ZipEntry using '...' instead of new ZipEntry("dir/")
 - Add @apiNote describing that directory entries should use the STORED compression method and have size and crc set to 0.

Changes: https://git.openjdk.org/jdk/pull/12899/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=12899&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8303923
  Stats: 16 lines in 1 file changed: 16 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/12899.diff
  Fetch: git fetch https://git.openjdk.org/jdk pull/12899/head:pull/12899

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