On Wed, 7 Jun 2023 16:02:40 GMT, Pavel Rappo <[email protected]> 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
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFinder.java
line 54:
> 52:
> 53: @SuppressWarnings("serial")
> 54: public static final class NoOverriddenMethodFound extends Exception {
General comment, for future work:
Maybe we can combine/merge/unify this exception with `ThrowsTaglet.Failure`
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
line 671:
> 669: // .anyMatch(t -> Objects.equals(typeUtils.asElement(t),
> typeUtils.asElement(t2)));
> 670:
> 671: return true; /* disabled for causing issues in JDK API
> Documentation build */
Please describe the issues and/or provide a JBS issue, so that we can decide
when to revert the code to the commented-out form.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222051685
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222053011
