On Thu, 8 Jun 2023 09:55:27 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".
>
> Pavel Rappo has updated the pull request incrementally with one additional
> commit since the last revision:
>
> feedback: remove unduly restrictive warning
src/java.base/share/classes/java/util/TreeMap.java line 1199:
> 1197: * {@code add} or {@code addAll} operations.
> 1198: *
> 1199: * @return {@inheritDoc SortedMap}
An alternative here might be add `{@return ...}` to the first sentence of the
method description so that the return description exactly matches.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222847956
