RFR: 8285368: Overhaul doc-comment inheritance [v2]

[Jonathan Gibbons]

On Wed, 7 Jun 2023 16:02:40 GMT, Pavel Rappo <prappo at openjdk.org> 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