On Mon, 12 Jun 2023 07:58:29 GMT, Chen Liang <li...@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
