On Wed, 7 Jun 2023 16:02:40 GMT, Pavel Rappo <pra...@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