RFR: 8308753: Class-File API transition to Preview [v3]

[Adam Sotona]

On Mon, 2 Oct 2023 13:26:38 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Adam Sotona has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   fixed javadoc typo
>
> src/java.base/share/classes/java/lang/classfile/CodeTransform.java line 101:
> 
>> 99: 
>> 100:     /**
>> 101:      * @implSpec The default implementation returns a resolved transform;
> 
> `... returns a resolved transform that is bound to the given code builder`
> or
> `... returns a resolved transform bound to the given code builder`

Fixed, thanks.

> src/java.base/share/classes/java/lang/classfile/MethodSignature.java line 59:
> 
>> 57: 
>> 58:     /**
>> 59:      * {@return method signature for a raw (no generic information) method descriptor}
> 
> Isn't this missing an article - e.g. `return the method signature` or `return a method signature` ?

Fixed, thanks.

> src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.java line 310:
> 
>> 308:          * @param implClasses the implementation classes
>> 309:          * @return this builder
>> 310:          * @throws IllegalArgumentException if {@code service} or any of the {@code implClasses} represents a primitive type
> 
> Javadoc tip (not that you should use that here) - if the thrown clause becomes too complex, you can also split it into multiple `throws IllegalArgumentException`. Sometimes that can improve readability.

Thanks!

> src/java.base/share/classes/java/lang/classfile/attribute/ModuleResolutionAttribute.java line 75:
> 
>> 73:      *  The value of the resolution_flags item is a mask of flags used to denote
>> 74:      *  properties of module resolution. The flags are as follows:
>> 75:      * <pre> {@code
> 
> Why not a snippet?

It is a citation from the spec, not sure a snippet would be appropriate.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/15706#discussion_r1342738626
PR Review Comment: https://git.openjdk.org/jdk/pull/15706#discussion_r1342745504
PR Review Comment: https://git.openjdk.org/jdk/pull/15706#discussion_r1342745325
PR Review Comment: https://git.openjdk.org/jdk/pull/15706#discussion_r1342748330