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

[Stuart Marks]

On Tue, 13 Jun 2023 10:11:28 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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 14 additional commits since the last revision:
> 
>  - fix failing SourceDocTreeScannerTest
>  - Merge branch 'master' into 8285368
>  - feedback: use JavadocTester.out
>    
>    Also, trivially fixes grammar (word order) in a comment.
>  - feedback: remove unduly restrictive warning
>  - suggestion: vocabulary
>  - feedback: DocLint terminology
>  - feedback: use utils directly
>  - Merge branch 'master' into 8285368
>  - feedback: make warning less scary
>  - Disable problematic check
>    
>    This check is well-intended but problematic for JDK API Documentation
>    build, which errors on warnings.
>  - ... and 4 more: https://git.openjdk.org/jdk/compare/332eaf7c...563a8761

I reviewed the changes in java.base. They look fine. I support the notion of keeping these changes minimal, with the narrow goal of keeping the resulting javadoc output the same. There are many opportunities for improving the actual docs, but those should be handled separately.

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

Marked as reviewed by smarks (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/14357#pullrequestreview-1478203733