On Fri, 17 Dec 2021 13:03:57 GMT, Jan Lahoda <jlah...@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
