On Wed, 7 Jun 2023 14:19:16 GMT, Pavel Rappo <pra...@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