RFR: 8215788: Clarify JarInputStream Manifest access

[Weijun Wang]

On Tue, 13 Sep 2022 20:58:04 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> src/java.base/share/classes/java/util/jar/JarInputStream.java line 36:
>> 
>>> 34:  * The {@code JarInputStream} class, which extends {@linkplain ZipInputStream},
>>> 35:  * is used to read the contents of a JAR file from an input stream.
>>> 36:  * It provides support for reading an optional {@linkplain JarFile#MANIFEST_NAME Manifest}
>> 
>> `Manifest` above is the same as the one below. If the one below is in fixed-width, so should be the one above.
>
> Could you please clarify what you are suggesting.  I am using the  `@linkplain` to provide a means to see the actual Manifest name.   I am happy to tweak, just need (perhaps an example) of what you would like

On lines 36 and 37, there are two "Manifest". The first uses `linkplain` so it's using normal font style, the 2nd uses `code` so it's fixed-width. I would like them to be the same. In fact, I would not use `linkplain` at all. I only use it when the text is not a Java identifier. For example, `{@linkplain SecurityManager the Security Manager}`. However in this PR, for all the places where you use it, the text is either a class name or a method name. I would just use `link`.

>> src/java.base/share/classes/java/util/jar/JarInputStream.java line 78:
>> 
>>> 76:  * <b>Note:</b>If a {@code JarEntry} is modified after the Jar file is signed,
>>> 77:  * a {@linkplain SecurityException} will be thrown when an attempt is made to
>>> 78:  * read the entry.
>> 
>> Not sure if the the `an attempt` word is precise. The exception is only thrown when the last byte is read.
>
> Are you suggesting change:
> 
> "...will be thrown when an attempt is made to read the entry."
> 
> to
> 
> "...will be thrown when the entry has been read."

Not sure. Maybe just `is read` is OK.

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

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