RFR: 8342466: Improve API documentation for java.lang.classfile.attribute

[Adam Sotona]

On Fri, 10 Jan 2025 07:32:24 GMT, Chen Liang <liach at openjdk.org> wrote:

> Improve documentation for `class` file attributes. This include better specification for user attributes, some more general information about attributes, such as the usage of non-JVMS attributes, and updated some attribute information in the base package too, such as Annotation and Signature.
> 
> APIDiff: https://cr.openjdk.org/~liach/apidiff/cf-attribute/
> Javadoc: https://cr.openjdk.org/~liach/javadoc/cf-attribute/java.base/java/lang/classfile/Attribute.html

Great documentation improvement, thank you.

Only minor nits are in the comments.

src/java.base/share/classes/java/lang/classfile/attribute/ModuleExportInfo.java line 71:

> 69:      * flag enums}
> 70:      *
> 71:      * @throws IllegalArgumentException if the flags mask has any unused bit set

I'm not sure "if the flags mask has any unused bit set" is clear to understand

src/java.base/share/classes/java/lang/classfile/attribute/ModuleOpenInfo.java line 77:

> 75:      * flag enums}
> 76:      *
> 77:      * @throws IllegalArgumentException if the flags mask has any unused bit set

dtto

src/java.base/share/classes/java/lang/classfile/attribute/ModuleRequireInfo.java line 68:

> 66:      * flag enums}
> 67:      *
> 68:      * @throws IllegalArgumentException if the flags mask has any unused bit set

dtto

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

> 28:  *
> 29:  * The {@code java.lang.classfile.attribute} package contains interfaces describing specific {@code class} file attributes.
> 30:  * General and user-defined attributes reside in {@link java.lang.classfile}, including {@link Attributes}, {@link

"General and user-defined attributes reside in java.lang.classfile" is a bit confusing to me.

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

Marked as reviewed by asotona (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23026#pullrequestreview-2542303434
PR Review Comment: https://git.openjdk.org/jdk/pull/23026#discussion_r1910299892
PR Review Comment: https://git.openjdk.org/jdk/pull/23026#discussion_r1910305291
PR Review Comment: https://git.openjdk.org/jdk/pull/23026#discussion_r1910307335
PR Review Comment: https://git.openjdk.org/jdk/pull/23026#discussion_r1910327178