RFR: 8283864: Clean up DocFinder and friends [v2]

[Jonathan Gibbons]

On Thu, 14 Apr 2022 09:20:08 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> 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.

Wow, OK, thanks for the update/info

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java line 89:
>> 
>>> 87:                 ? null
>>> 88:                 : configuration.tagletManager.getTaglet(ch.getTagName(holderTag));
>>> 89:         if (taglet != null && !(taglet instanceof InheritableTaglet)) {
>> 
>> Optional, this is a possible use case for patterns in `instanceof` ... you could declare a name here and save the cast on line 95
>
> I think `taglet != null` gets in the way. I tried to change the order of conjuncts, but to no avail: flow scoping analysis seems to give up. Might be something that the compiler folks can comment on.

Noted

-------------

PR: https://git.openjdk.java.net/jdk/pull/8229