On Wed, 13 Apr 2022 23:04:22 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
>> A clean-up to facilitate more clean-up in the future.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java
> line 46:
>
>> 44: /**
>> 45: * An inline taglet representing the {@code {@inheritDoc}} tag.
>> 46: * It is used to copy documentation from superclass (but not
>> superinterface)
>
> is that true,(not super interfaces)?
>
> what about when `{@inheritDoc}` is used in interfaces?
Yes, this is true [^1]. Superinterfaces are currently unsupported. Even
inhereting documentation from a class declaration (i.e. the top-level comment)
is unofficial; it was rather an unintended consequence of JDK-8008768.
That said, inhereting documentation from a class or interface declaration seems
useful. It should be fixed and made official through a CSR. I thought that it's
quite a lot of work which shouldn't be done in a cleanup PR such as this one.
My goal here is to make the internal comments accurate and up to date.
[^1]: Have a look here:
https://github.com/openjdk/jdk/blob/5896905ff06a83a9960ac2a2c5974c471ccd0666/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFinder.java#L261-L272
Consider that `TypeElement.getSuperclass()` never returns interfaces.
-------------
PR: https://git.openjdk.java.net/jdk/pull/8229
