RFR: 8338014: Improve usage of @jvms tags in class file API

[Chen Liang]

On Thu, 8 Aug 2024 18:15:29 GMT, Sonia Zaldana Calles <szaldana at openjdk.org> wrote:

> Hi all, 
> 
> This PR addresses [8338014](https://bugs.openjdk.org/browse/JDK-8338014) improving the use of `@jvms` tags by adding `JVMS` prior to the tag. 
> 
> Thanks, 
> Sonia

Changes requested by liach (Reviewer).

src/java.base/share/classes/java/lang/classfile/Attribute.java line 69:

> 67: 
> 68: /**
> 69:  * Models a classfile attribute JVMS {@jvms 4.7}.  Many, though not all, subtypes of

Suggestion:

 * Models a classfile attribute (JVMS {@jvms 4.7}).  Many, though not all, subtypes of

Same as for all other attributes.

src/java.base/share/classes/java/lang/classfile/TypeAnnotation.java line 63:

> 61: 
> 62: /**
> 63:  * Models an annotation on a type use, as defined in JVMS {@jvms 4.7.19} and JVMS {@jvms 4.7.20}.

Suggestion:

 * Models an annotation on a type use, as defined in JVMS {@jvms 4.7.19} and {@jvms 4.7.20}.

src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.java line 37:

> 35: 
> 36: /**
> 37:  * Models the {@code Synthetic} attribute JVMS {@jvms 4.7.8}, which can appear on

These occurrences should be `(JVMS {@jvms x.x.x})`.

src/java.base/share/classes/java/lang/classfile/constantpool/ConstantPoolBuilder.java line 368:

> 366:      * returned.
> 367:      *
> 368:      * @param refKind the reference kind of the method handle JVMS {@jvms 4.4.8}

Same, these occurrences are not part of a sentence, so enclose in parentheses like `(JVMS {@jvms 4.4.8})`

src/java.base/share/classes/java/lang/classfile/package-info.java line 1:

> 1: /*

These 2 changes are redundant and wrong. Please review your changes before submitting it after mechanical replacements.

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

PR Review: https://git.openjdk.org/jdk/pull/20513#pullrequestreview-2233779488
PR Review Comment: https://git.openjdk.org/jdk/pull/20513#discussion_r1714226622
PR Review Comment: https://git.openjdk.org/jdk/pull/20513#discussion_r1714226304
PR Review Comment: https://git.openjdk.org/jdk/pull/20513#discussion_r1714224992
PR Review Comment: https://git.openjdk.org/jdk/pull/20513#discussion_r1714225652
PR Review Comment: https://git.openjdk.org/jdk/pull/20513#discussion_r1714224171