On Wed, 7 Jun 2023 16:02:40 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: 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