RFR: 8277300: Issues with javadoc support for preview features [v2]

[Jonathan Gibbons]

On Fri, 17 Dec 2021 13:03:57 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

>> This is a patch that tweaks a bit the PREVIEW superscript which is marking preview APIs in javadoc. This is based on the experience with the Loom's fibers javadoc.
>> 
>> Namely, the changes are:
>> 
>>  * for methods inside a preview class:
>>    * show the PREVIEW superscript, unless:
>>    * the reference is inside the enclosing (preview) class, in which case skip the PREVIEW superscript
>>    * ensure the PREVIEW superscript refers to the class' Preview note, not to the non-existing method's Preview note
>> * for preview classes nested inside preview classes, ensure these are considered preview by themselves, not only as referring to a preview class
>> * avoid the PREVIEW superscript inside code snippets.
>> 
>> A sample javadoc with these changes is here:
>> http://cr.openjdk.java.net/~jlahoda/8277300/fibers-docs.00/api/java.base/java/util/concurrent/StructuredExecutor.html
>> http://cr.openjdk.java.net/~jlahoda/8277300/fibers-docs.00/api/java.base/java/util/concurrent/StructuredExecutor.CompletionHandler.html
>
> Jan Lahoda 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 four additional commits since the last revision:
> 
>  - Merge branch 'master' into JDK-8277300
>  - Cleanup
>  - Cleanup
>  - 8277300: Issues with javadoc support for preview features

Almost there. Some minor comments and a method name typo to be fixed.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 3112:

> 3110:     }
> 3111: 
> 3112:     private boolean hasNoProviewAnnotation(Element el) {

typo in  method name, `hasNoProviewAnnotation`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 3131:

> 3129:                     !previewAPIs.reflectivePreviewAPI.isEmpty() ||
> 3130:                     !previewAPIs.declaredUsingPreviewFeature.isEmpty()) &&
> 3131:                    !hasNoProviewAnnotation(el);

Minor grumbles.

1. Normal JDK code style is to put binary operators at the beginning of a line, not the end of a previous line
2. It would help a bit to use more indentation to show the `&&` groups
3. last line is inconsistently indented

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 3131:

> 3129:                     !previewAPIs.reflectivePreviewAPI.isEmpty() ||
> 3130:                     !previewAPIs.declaredUsingPreviewFeature.isEmpty()) &&
> 3131:                    !hasNoProviewAnnotation(el);

Typo in method name `hasNoProviewAnnotation`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 3144:

> 3142:     public interface PreviewFlagProvider {
> 3143:         public boolean isPreview(Element el);
> 3144:     }

nice

test/langtools/jdk/javadoc/doclet/testPreview/api2/api/API.java line 2:

> 1: /*
> 2:  * Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.

This and other copyright years should now be 2022

test/langtools/jdk/javadoc/doclet/testPreview/api2/api/API2.java line 2:

> 1: /*
> 2:  * Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.

2022

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

Marked as reviewed by jjg (Reviewer).

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