RFR: 8309819: Clarify API note in Class::getName and MethodType::toMethodDescriptorString [v4]

[Alan Bateman]

On Wed, 14 Jun 2023 02:13:23 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/03/java.base/java/lang/Class.html
>> https://cr.openjdk.org/~liach/8309819/03/java.base/java/lang/invoke/MethodType.html
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Convert the note in fromDescriptorString to apiNote

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

> 926:      * @apiNote
> 927:      * This is not a strict inverse of {@link #forName(String) forName}.
> 928:      * For normal classes, distinct classes which share a common name but

Readers may wonder what "normal classes" means here, it might be simpler to just drop introducing that term and just use the structure from the note removed from descriptorString.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14411#discussion_r1229028888