RFR: 8215788: Clarify JarInputStream Manifest access [v3]

[Alan Bateman]

On Wed, 14 Sep 2022 10:31:41 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:
> 
>   Address a couple of typos in  Note

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

> 42:  * The {@link #getManifest} method will return the {@code Manifest} when it is
> 43:  * the first entry in the stream or {@code META-INF/} is the first entry and
> 44:  * the {@code Manifest} is the second entry within the stream. When the

I think you can insert a comma after "when it is the first entry in the stream"? I think that would make it a bit clearer that there are two cases.

Also I'm wondering if the paragraph should be split into two, meaning "When the Manifest ..."  can be the start of a new paragraph. The reason is that the text is trying to explain two things, the first is that the manifest must be at the start of the JAR file, the second is that the ordering that methods are invoked will influence how other methods behave.

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

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