RFR: 8283864: Clean up DocFinder and friends

[Pavel Rappo]

On Wed, 13 Apr 2022 23:04:22 GMT, Jonathan Gibbons <jjg at 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