8278165: Clarify that ZipInputStream does not access the CEN fields f…

…or a ZipEntry

Reviewed-by: bpb, alanb

src/java.base/share/classes/java/util/zip/ZipInputStream.java

@@ -38,9 +38,36 @@
 import static java.util.zip.ZipUtils.*;
 
 /**
- * This class implements an input stream filter for reading files in the
- * ZIP file format. Includes support for both compressed and uncompressed
- * entries.
+ * An input stream for reading compressed and uncompressed
+ * {@linkplain ZipEntry ZIP file entries} from a stream of bytes in the ZIP file
+ * format.
+ *
+ * <H2>Reading Zip File Entries</H2>
+ *
+ * The {@link #getNextEntry()} method is used to read the next ZIP file entry
+ * (Local file (LOC) header record in the ZIP format) and position the stream at
+ * the entry's file data. The file data may read using one of the
+ * {@code ZipInputStream} read methods such
+ * as {@link #read(byte[], int, int) read} or {@link #readAllBytes() readAllBytes()}.
+ * For example:
+ *    {@snippet :
+ *      Path jar = Path.of("foo.jar");
+ *      try (InputStream is = Files.newInputStream(jar);
+ *           ZipInputStream zis = new ZipInputStream(is)) {
+ *          ZipEntry ze;
+ *          while((ze= zis.getNextEntry()) != null) {
+ *             var bytes = zis.readAllBytes();
+ *             System.out.printf("Entry: %s, bytes read: %s%n", ze.getName(),
+ *                     bytes.length);
+ *          }
+ *      }
+ *    }
+ * @apiNote
+ * The LOC header contains metadata about the Zip file entry. {@code ZipInputStream}
+ * does not read the Central directory (CEN) header for the entry and therefore
+ * will not have access to its metadata such as the external file attributes.
+ * {@linkplain ZipFile} may be used when the information stored within
+ * the CEN header is required.
  *
  * @author      David Connelly
  * @since 1.1