On Wed, 7 Jun 2023 16:02:40 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 incrementally with one additional
> commit since the last revision:
>
> feedback: make warning less scary
Full disclosure. Here are all the files that are different before (1) and after
(2) the change:
- https://cr.openjdk.org/~prappo/8285368/1/api
- https://cr.openjdk.org/~prappo/8285368/2/api
As you can see, the vast majority of differences are in "See Also" sections,
which come from `@see` tags. Sadly, `@see` tags are inheritable "by omission".
That said, `@see` is also underspecified, somewhat broken, and I believe is not
as important as those parts of a doc comment that allow `{@inheritDoc}`.
I suggest that we integrate this PR and take care of `@see` in 22. But if the
corrections are really required, I can try to introduce explicit `@see` tags,
so there are no changes whatsoever.
-------------
PR Comment: https://git.openjdk.org/jdk/pull/14357#issuecomment-1581226538
