RFR: 8285368: Overhaul doc-comment inheritance

[Jonathan Gibbons]

On Wed, 7 Jun 2023 14:19:16 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".

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1325:

> 1323:                         //
> 1324:                         //     m.at(pos).newInheritDocTree(ref)
> 1325:                         //

Although the scary warning is not wrong, I think it would have been enough to say something more concise, like "_use the original legacy method if no ref is given_"

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

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