RFR: 8285368: Overhaul doc-comment inheritance [v2]

[Jonathan Gibbons]

On Wed, 7 Jun 2023 16:02:40 GMT, Pavel Rappo <prappo at 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