RFR: JDK-8319122: Improve documentation of various Zip-file related APIs [v3]

[Yakov Shafranovich]

> The various Zip/Jar-file related Java APIs have some long-standing differences or peculiarities with respect to the ZIP-file specification or compared to other implementations which should be documented in the API-doc. This documents the following:
> - Cache of JAR files in JarURLConnection class
> - Cache of JAR/ZIP files in JarFile and ZipFile classes
> - Unexpected behavior when parsing ZIP files with duplicate entries in JarFile and ZipFile classes, as well as the zipfs provider
> - Directories and filenames with the same name considered to be the same in ZipFile class
> - Possible issues when local and central headers conflict in ZipInputStream class
> 
> Related JBS report:
> https://bugs.openjdk.org/browse/JDK-8319122

Yakov Shafranovich has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains five additional commits since the last revision:

 - reverted zipfs changes and made adjustements for ZipInputStream comments
 - Merge branch 'master' into zip-doc-changes
 - Fixed more line breaks
 - fixed line breaks
 - document patch for JDK-8319122

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16424/files
  - new: https://git.openjdk.org/jdk/pull/16424/files/919666a0..dbecd485

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16424&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16424&range=01-02

  Stats: 831197 lines in 4897 files changed: 202043 ins; 545027 del; 84127 mod
  Patch: https://git.openjdk.org/jdk/pull/16424.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16424/head:pull/16424

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