/* * Copyright (c) 2003, 2025, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ /* * @test * @bug 8250768 8261976 8277300 8282452 8287597 8325325 8325874 8297879 * 8331947 8281533 8343239 8318416 8346109 8359024 * @summary test generated docs for items declared using preview * @library /tools/lib ../../lib * @modules jdk.javadoc/jdk.javadoc.internal.tool * jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.resources:+open * @build toolbox.ToolBox javadoc.tester.* * @run main TestPreview */ import java.io.IOException; import java.nio.file.Path; import java.nio.file.Paths; import javadoc.tester.JavadocTester; import toolbox.ToolBox; public class TestPreview extends JavadocTester { ToolBox tb = new ToolBox(); public static void main(String... args) throws Exception { var tester = new TestPreview(); tester.runTests(); } @Test public void testUserJavadoc() { String doc = Paths.get(testSrc, "doc").toUri().toString(); javadoc("-d", "out-user-javadoc", "-XDforcePreview", "--enable-preview", "-source", System.getProperty("java.specification.version"), "--patch-module", "java.base=" + Paths.get(testSrc, "api").toAbsolutePath().toString(), "--add-exports", "java.base/preview=m", "--module-source-path", testSrc, "-linkoffline", doc, doc, "m/pkg"); checkExit(Exit.OK); checkOutput("m/pkg/TestPreviewDeclarationUse.html", true, "TestPreviewDeclaration"); checkOutput("m/pkg/TestPreviewAPIUse.html", true, "CorePREVIEW"); checkOutput("m/pkg/DocAnnotation.html", true, "public @interface DocAnnotation"); checkOutput("m/pkg/DocAnnotationUse1.html", true, "
pkg.DocAnnotationUse1
"); checkOutput("m/pkg/DocAnnotationUse2.html", true, "
pkg.DocAnnotationUse2
"); } @Test public void testPreviewAPIJavadoc() { javadoc("-d", "out-preview-api", "--patch-module", "java.base=" + Paths.get(testSrc, "api").toAbsolutePath().toString(), "--add-exports", "java.base/preview=m", "--source-path", Paths.get(testSrc, "api").toAbsolutePath().toString(), "--show-packages=all", "preview"); checkExit(Exit.OK); checkOutput("preview-list.html", true, """

Contents

""", """
Packages
Package
Preview Feature
Description
previewPREVIEW
Test Feature
Preview package.
""", """
Record Classes
Record Class
Preview Feature
Description
preview.CoreRecordPREVIEW
Test Feature
""", """
Methods
Method
Preview Feature
Description
preview.CoreRecordComponent.i()<\ a href="java.base/preview/CoreRecordComponent.html#preview-i()">PREVIEW
Test Feature
Returns the value of the i record component.
"""); // 8325325: Breadcrumb navigation links should not contain PREVIEW link checkOutput("java.base/preview/package-summary.html", true, """
  1. java.base
  2. preview
"""); checkOutput("java.base/preview/Core.html", true, """
  1. java.base
  2. preview
  3. Core
""", """
Preview feature. Links: CoreRecordPREVIEW, core recordPREVIEW, CoreRecord, core record.
""", """
  • CoreRecord<\ /a>PREVIEW
  • core record
    • """); // 8331947: Support preview features without JEP should not be included in Preview API page checkOutput("preview-list.html", false, "supportMethod"); } // 8343239 pre-existing permanent API that is later retrofitted // to extend a @PreviewFeature interface should not be flagged as a preview feature @Test public void nonPreviewExtendsPreview(Path base) throws IOException { Path src = base.resolve("src"); tb.writeJavaFiles(src, """ package p; import jdk.internal.javac.PreviewFeature; /** * Preview feature */ @PreviewFeature(feature= PreviewFeature.Feature.TEST) public interface CoreInterface { } """, """ package p; /** * Non preview feature */ public interface NonPreviewExtendsPreview extends CoreInterface { default int getNumber() { return 0; } } """); javadoc("-d", "out-non-preview-extends-preview", "--add-exports", "java.base/jdk.internal.javac=ALL-UNNAMED", "--source-path", src.toString(), "p"); checkExit(Exit.OK); checkOutput("p/NonPreviewExtendsPreview.html", false, """ NonPreviewExtendsPreview relies on preview features of the Java platform: """, """ NonPreviewExtendsPreview refers to one or more preview APIs: """); checkOutput("p/CoreInterface.html", true, """
    public interface CoreInterface
    CoreInterface is a preview API of the Java platform.
    Programs can only use CoreInterface when preview features are enabled.
    Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
    Preview feature
    """); } @Test public void test8277300() { javadoc("-d", "out-8277300", "--add-exports", "java.base/jdk.internal.javac=api2", "--source-path", Paths.get(testSrc, "api2").toAbsolutePath().toString(), "--show-packages=all", "api2/api"); checkExit(Exit.OK); checkOutput("api2/api/API.html", true, "

    test()

    ", "

    testNoPreviewInSig()

    ", "title=\"interface in java.util\" class=\"external-link\">List<APIPREVIEW>"); checkOutput("api2/api/API2.html", true, "API.test()PREVIEW", "API.testNoPreviewInSig()PREVIEW", "API3.test()PREVIEW"); checkOutput("api2/api/API3.html", true, "
    test()<" + "a href=\"#preview-test()\">PREVIEW
    "); } @Test public void test8282452() { javadoc("-d", "out-8282452", "--patch-module", "java.base=" + Paths.get(testSrc, "api").toAbsolutePath().toString(), "--add-exports", "java.base/preview=m", "--source-path", Paths.get(testSrc, "api").toAbsolutePath().toString(), "--show-packages=all", "preview"); checkExit(Exit.OK); checkOutput("java.base/preview/NoPreview.html", false, "refers to one or more preview"); } @Test public void testRequiresTransitiveJavaBase() { Path src = Paths.get(testSrc, "requiresTransitiveJavaBase"); javadoc("-d", "out-requires-transitive-java-base", "-XDforcePreview", "--enable-preview", "-source", System.getProperty("java.specification.version"), "--module-source-path", src.toString(), "--module", "m", "--expand-requires", "transitive"); checkExit(Exit.OK); checkOutput("m/module-summary.html", true, "Indirect exports from the java.base module are"); } // Test for JDK hidden option to add an entry for a non-preview element // in the preview page based on the presence of a javadoc tag. @Test public void testPreviewNoteTag(Path base) throws IOException { Path src = base.resolve("src"); tb.writeJavaFiles(src, """ package p; import jdk.internal.javac.PreviewFeature; /** * Preview feature */ @PreviewFeature(feature= PreviewFeature.Feature.TEST) public interface CoreInterface { } """, """ package p; /** * Non preview feature. * {@previewNote 2147483647 Preview API Note} */ public interface NonPrevieFeature { } """); javadoc("-d", "out-preview-note-tag", "--add-exports", "java.base/jdk.internal.javac=ALL-UNNAMED", "-tag", "previewNote:a:Preview Note:", "--preview-note-tag", "previewNote", "--source-path", src.toString(), "p"); checkExit(Exit.OK); checkOutput("preview-list.html", true, """

    Contents