On Tue, 13 Jun 2023 10:11:28 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 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/79d4fbab...563a8761
Looks good to me for client changes.
-------------
Marked as reviewed by aivanov (Reviewer).
PR Review: https://git.openjdk.org/jdk/pull/14357#pullrequestreview-1477876414
