RFR: 8343239: Javadoc marks non-preview type as preview if it's the subtype of a preview type [v2]

[Hannes Wallnöfer]

On Fri, 22 Nov 2024 14:36:39 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this patch to improve the javadoc preview header. The parent bug include more details.
>> 
>> This is meant to prevent a bug where, if a non preview class extend an `@PreviewFeature` interface, the Javadoc displays `Programs can only use <<Type>> when preview features are enabled` when the API can be used without enable preview features as long as we don't refer to any methods in the supertype
>> 
>> This is specifically the case in  #17543. Here is the javadoc output [AsymmetricKey](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8343239-2/docs/api/java.base/java/security/AsymmetricKey.html) after merging this branch with the PR `298420: PEM API: Implementation (Preview) #17543`. The only files affected by this change are the class `DEREncodable` and it's Subinterfaces.
>> 
>> One other bug I noticed is that, on the `DEREncodable` page, it's direct subinterfaces had the superscript `PREVIEW` link. I've added a condition to remove it.
>
> Nizar Benalla has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains five additional commits since the last revision:
> 
>  - dropping earlier idea/message as non-preview class should not have a preview message. As you do not need --enable-preview to use them.
>    
>    Removed some code and modified test accordingly
>  - Merge remote-tracking branch 'upstream/master' into javadoc-preview-message
>  - remove unused import
>  - improve preview label message
>  - fix preview bug

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 2519:

> 2517:             target.add(previewDiv);
> 2518:         } else if ((forWhat.getKind().isClass() || forWhat.getKind().isInterface())
> 2519:                 && !utils.nonPreviewExtendsPreview(forWhat)) {

It appears you are excluding a type from getting a preview notice by checking a condition that is elsewhere used to decide it needs a preview notice. IMO the better solution would be to not give it a preview notice in the first place by not checking implemented interfaces for classes in `Utils.declaredUsingPreviewAPIs(Element)`. (An interface extending a preview interface is a different again, although I don't think that should ever occur in the JDK.)

That leaves open the case where a preview interface introduces a default method (which is being fixed for javac in [JDK-8343540](https://bugs.openjdk.org/browse/JDK-8343540)), but I would consider that a separate issue.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/22126#discussion_r1857231522