RFR: 8339329: ConstantPoolBuilder#constantValueEntry method doc typo and clarifications [v2]

[Chen Liang]

On Fri, 30 Aug 2024 18:12:38 GMT, David M. Lloyd <duke at openjdk.org> wrote:

>> Please review this small documentation change to ConstantPoolBuilder to fix a typo and clarify the usage of the `constantValueEntry` method.
>
> David M. Lloyd has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Review comments

Also since this is just adding links, I don't think this needs a CSR (compare to the similar cleanup Joe Darcy is doing to the `java.lang` and math content).

src/java.base/share/classes/java/lang/classfile/Attributes.java line 251:

> 249:      * {@return Attribute mapper for the {@code ConstantValue} attribute}
> 250:      * @since 23
> 251:      * @see java.lang.classfile.constantpool.ConstantPoolBuilder#constantValueEntry(java.lang.constant.ConstantDesc)

Suggestion:


Redundant here. People can probably follow the link on the type argument.

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

> 479:      *
> 480:      * @param c the constant
> 481:      * @see java.lang.classfile.Attributes#constantValue()

Suggestion:

     * @see ConstantValueEntry#constantValue()

as it's the reverse operation of this.

src/java.base/share/classes/java/lang/classfile/constantpool/ConstantValueEntry.java line 46:

> 44:      * {@link Long}, {@link Float}, {@link Double}, or {@link String}.
> 45:      *
> 46:      * @see java.lang.classfile.Attributes#constantValue()

I wish you can:
1. Add a link on the `{@code ConstantValue}` in class main javadoc so it's like `{@link ConstantValueAttribute ConstantValue}` or `{@link Attributes#constantValue ConstantValue}`
2. Change the `@see` link to `ConstantPoolBuilder#constantValueEntry` as that pairs up with this method.

Suggestion:

     * @see ConstantPoolBuilder#constantValueEntry(ClassDesc)

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

PR Comment: https://git.openjdk.org/jdk/pull/20796#issuecomment-2380870658
PR Review Comment: https://git.openjdk.org/jdk/pull/20796#discussion_r1779740219
PR Review Comment: https://git.openjdk.org/jdk/pull/20796#discussion_r1779740185
PR Review Comment: https://git.openjdk.org/jdk/pull/20796#discussion_r1779739929