On Wed, 7 Jun 2023 16:02:40 GMT, Pavel Rappo <[email protected]> wrote:
>> Please review this long-awaited change to documentation inheritance.
>>
>> This change improves "methods comment algorithm" and introduces directed
>> documentation inheritance. While "methods comment algorithm" -- automatic
>> search for inheritable documentation -- has been improved, it still cannot
>> read an author's mind so as to always find the documentation they intended.
>> From now on, an author can state their intention, by providing an FQN of the
>> superclass or superinterface from which to inherit documentation:
>>
>> {@inheritDoc S}
>>
>> Which is exactly what I did to counterbalance some of the JDK API
>> Documentation changes caused by the change to "methods comment algorithm".
>
> Pavel Rappo has updated the pull request incrementally with one additional
> commit since the last revision:
>
> feedback: make warning less scary
test/langtools/jdk/javadoc/doclet/testDirectedInheritance/TestDirectedInheritance.java
line 75:
> 73: // code is OK, it likely isn't (after all, there's an unknown
> tag).
> 74: setAutomaticCheckNoStacktrace(true);
> 75: { // DocLint is on
"on" -> "explicit"
test/langtools/jdk/javadoc/doclet/testDirectedInheritance/TestDirectedInheritance.java
line 85:
> 83: }
> 84: }
> 85: // DocLint is off
"off" -> "default"
test/langtools/jdk/javadoc/doclet/testDirectedInheritance/TestDirectedInheritance.java
line 289:
> 287:
> 288: /*
> 289: * C1.m inherits documentation from B1.m explicitly and undirect.
possible typo: do you mean "indirect"
test/langtools/jdk/javadoc/doclet/testDirectedInheritance/TestDirectedInheritance.java
line 673:
> 671: *
> 672: * For now a warning is issued if a doc comment inherits from
> 673: * an indirect supertype.
Not sure I agree with this. Can we discuss?
test/langtools/jdk/javadoc/doclet/testMethodCommentAlgorithm/TestMethodCommentsAlgorithm.java
line 61:
> 59: import toolbox.ToolBox;
> 60:
> 61: /*
Great description! :-)
test/langtools/jdk/javadoc/doclet/testMethodCommentAlgorithm/TestMethodCommentsAlgorithm.java
line 111:
> 109: * built.
> 110: */
> 111: public class TestMethodCommentsAlgorithm extends JavadocTester {
General comment for entire class: great/clever test!
test/langtools/jdk/javadoc/doclet/testMethodCommentAlgorithm/TestMethodCommentsAlgorithm.java
line 273:
> 271: }
> 272: }
> 273: System.err.println("Test suite root: " + p);
You might want to use `JavadocTester.out` instead of `System.err`
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222117577
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222117867
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222119420
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222122630
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222124323
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222130052
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222126057
