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

[Jonathan Gibbons]

On Wed, 7 Jun 2023 20:48:58 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> 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?
>
> Sure we can; this relates to an earlier comment of yours on Utils.isDirectSupertype here: https://github.com/openjdk/jdk/pull/14357#discussion_r1222053011

The general criticism here is whether we should restrict in any way the set of super types from which one can inherit documentation, and/or what should the set of checks be?

For example, if a method in C inherits a method in B that has no comment but which inherits a method with a comment in A, then it seems unduly restrictive to stop the method in C explicitly referencing the method in A, as compared to only allowing a reference to B, which implicitly gets its comment from A.

That being said, there is merit in starting off with restrictions and loosening them in the face of experience, rather than trying to increase the stylistic restrictions later.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222202085