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

[Pavel Rappo]

On Wed, 7 Jun 2023 16:02:40 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 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