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/taglets/InheritDocTaglet.java line 94: > 92: if (supertype == null) { > 93: messages.error(inheritDocPath, > "doclet.inheritDocBadSupertype"); > 94: return replacement; `replacement` may be empty. Consider using `HtmlDocletWriter.invalidTagOutput`. (Later, we might want to provide a utility message to wrap `messages.error` and `invalidTagOutput` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java line 110: > 108: for (Element e : methods) { > 109: ExecutableElement m = (ExecutableElement) e; > 110: if (configuration.utils.elementUtils.overrides(method, > m, (TypeElement) method.getEnclosingElement())) { Suggestion for eventual future cleanup (not this PR): reduce need for chained fields like`config.utils.elementUtils` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java line 110: > 108: for (Element e : methods) { > 109: ExecutableElement m = (ExecutableElement) e; > 110: if (configuration.utils.elementUtils.overrides(method, > m, (TypeElement) method.getEnclosingElement())) { Note that `configuration.utils` is available as `utils` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java line 120: > 118: // that this method overrides > 119: messages.error(inheritDocPath, > "doclet.inheritDocBadSupertype"); > 120: return replacement; Another case for `invalidTagOutput` ? ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222037366 PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222032679 PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222035009 PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222037884