RFR: 8215788: Clarify JarInputStream Manifest access [v8]

[Sean Mullan]

On Mon, 19 Sep 2022 17:25:53 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:
> 
>   Minor clarification for verifying an JarInputStream

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

> 42:  * <p>
> 43:  * The {@link #getManifest() getManifest} method is used to return the
> 44:  * <a href="{@docRoot}/../specs/jar/jar.html#jar-manifest">JAR Manifest</a>

Is it necessary to put "JAR" before "Manifest"? In the previous paragraph, you did not.

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

> 44:  * <a href="{@docRoot}/../specs/jar/jar.html#jar-manifest">JAR Manifest</a>
> 45:  * from the entry {@code META-INF/MANIFEST.MF} when it is the first entry
> 46:  * in the stream (or the second entry the first entry in the stream is

missing "if": "or the second entry if ..."

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 the first entry in the stream is
> 47:  * {@code META-INF/} and the second entry {@code META-INF/MANIFEST.MF}).

Missing "is": "and the second entry is ..."

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

> 46:  * in the stream (or the second entry the first entry in the stream is
> 47:  * {@code META-INF/} and the second entry {@code META-INF/MANIFEST.MF}).
> 48:  *</p>

Nit, add space after "*".

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

> 57:  * </p>
> 58:  *
> 59:  *  <h2>Verifying a JarInputStream</h2>

Is there a reason this is indented one extra space?

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

> 147:     /**
> 148:      * Returns the {@code Manifest} for this JAR file when it is the first entry
> 149:      * in the stream (or the second entry the first entry in the stream is

missing "if": "or the second entry if ..."

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

> 148:      * Returns the {@code Manifest} for this JAR file when it is the first entry
> 149:      * in the stream (or the second entry the first entry in the stream is
> 150:      * {@code META-INF/} and the second entry {@code META-INF/MANIFEST.MF}), or

Missing "is": "and the second entry is ..."

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

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