RFR: 8309819: Fix specification about descriptor inverses in Class and MethodType

[Mandy Chung]

On Mon, 12 Jun 2023 07:58:29 GMT, Chen Liang <liach at openjdk.org> wrote:

> The API specification for descriptorString not being a strict inverse of Class::forName and MethodType::fromDescriptorString are not entirely correct.
> 
> 1. Class::descriptorString was never an inverse of Class::forName, which takes a binary name instead. Class::getName was a partial inverse instead.
> 2. MethodType::toMethodDescriptorString ends with a meaningless sentence: "fromMethodDescriptorString, because the latter requires a suitable class loader argument.", and the "Note:" section can be replaced with an `@apiNote`.
> 3. Both of these didn't mention hidden classes (or other non-nominally-describable classes) as a reason that prevents the inversion operation, in addition to distinct classloaders.
> 
> A few user-defined anchor links are replaced with updated javadoc link tag format as well. The explicit html-style links in `@see` tags are unchanged in order to retain the non-code output.
> 
> The rendered specifications:
> https://cr.openjdk.org/~liach/8309819/00/java.base/java/lang/Class.html
> https://cr.openjdk.org/~liach/8309819/00/java.base/java/lang/invoke/MethodType.html

Looks good with minor suggestion.

src/java.base/share/classes/java/lang/Class.java line 930:

> 928:      * distinct classes may share a common name but have different class loaders.
> 929:      * In addition, {@linkplain #isHidden() hidden} classes cannot be discovered
> 930:      * by {@code forName}.

Suggestion:

     * This is not a strict inverse of {@link #forName(String) forName}.
     * For normal classes, distinct classes which share a common name but
     * have different class loaders will have the identical name.
     * In addition, {@linkplain #isHidden() hidden} classes cannot be
     * discovered by {@code forName}.

src/java.base/share/classes/java/lang/Class.java line 4551:

> 4549:      *
> 4550:      * @apiNote
> 4551:      * Distinct classes which share a common name but have different class loaders

I think this apiNote can be dropped.

src/java.base/share/classes/java/lang/invoke/MethodType.java line 1233:

> 1231:      * will appear identical when viewed within descriptor strings.
> 1232:      * In addition, the result string is not a bytecode descriptor if this
> 1233:      * method type cannot be {@linkplain ##descriptor described nominally}.

This method is equivalent to `MethodType::descriptorString` which specifies the result descriptor string if a method type descriptor not.  So I think this  sentence may not be needed.

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

PR Review: https://git.openjdk.org/jdk/pull/14411#pullrequestreview-1478104654
PR Review Comment: https://git.openjdk.org/jdk/pull/14411#discussion_r1228733587
PR Review Comment: https://git.openjdk.org/jdk/pull/14411#discussion_r1228732913
PR Review Comment: https://git.openjdk.org/jdk/pull/14411#discussion_r1228732670