RFR: 8215788: Clarify JarInputStream Manifest access [v12]

[Sean Mullan]

On Tue, 20 Sep 2022 18:08:23 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> Please review this PR which updates  the JarInputStream class description to clarify when the Manifest is accessible via JarInputStream::getManifest and JarInputStream::get[Jar]Entry.
>> 
>> It is worth noting that with this update, we are finally documenting  behavior that dates back to when this class was added to JDK 1.2
>> 
>> 
>> Best,
>> Lance
>
> Lance Andersen has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Added the verification note from JarFile

Some minor comments. Consider it reviewed either way.

src/java.base/share/classes/java/util/jar/JarInputStream.java line 43:

> 41:  * <h2>Accessing the Manifest</h2>
> 42:  * <p>
> 43:  * The {@link #getManifest() getManifest} method is used to return the

I think this can be more simply said as "... method returns the ..."

src/java.base/share/classes/java/util/jar/JarInputStream.java line 47:

> 45:  * from the entry {@code META-INF/MANIFEST.MF} when it is the first entry
> 46:  * in the stream (or the second entry if the first entry in the stream is
> 47:  * {@code META-INF/} and the second entry is {@code META-INF/MANIFEST.MF}).

Do you also want to say "Otherwise, the method returns `null`."

src/java.base/share/classes/java/util/jar/JarInputStream.java line 50:

> 48:  * </p>
> 49:  * <p> The {@link #getNextJarEntry()} and {@link #getNextEntry()} methods are
> 50:  * used to read JAR file entries from the stream. These methods skip over the

Consider removing "are used to". Just say "... methods read ...".

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

Marked as reviewed by mullan (Reviewer).

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