On Wed, 7 Jun 2023 15:27:28 GMT, Jonathan Gibbons <j...@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_"
I'll tone it down; thanks
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1221821265
