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
