8263468: New page for "recent" new API

Reviewed-by: erikj, jjg

Author: hns

make/Docs.gmk

@@ -332,6 +332,12 @@ define SetupApiDocsGenerationBody
   $$(eval $$(call create_overview_file,$1))
   $1_OPTIONS += -overview $$($1_OVERVIEW)
 
+  # Add summary pages for new/deprecated APIs in recent releases
+  $1_OPTIONS += --since $(call CommaList, \
+      $(filter-out $(VERSION_DOCS_API_SINCE), \
+          $(call sequence, $(VERSION_DOCS_API_SINCE), $(VERSION_FEATURE))))
+  $1_OPTIONS += --since-label "New API since JDK $(VERSION_DOCS_API_SINCE)"
+
   $$(foreach g, $$($1_GROUPS), \
     $$(eval $1_OPTIONS += -group "$$($$g_GROUP_NAME)" "$$($$g_GROUP_MODULES)") \
   )

make/autoconf/jdk-version.m4

@@ -533,6 +533,7 @@ AC_DEFUN_ONCE([JDKVER_SETUP_JDK_VERSION_NUMBERS],
   # We could define --with flags for these, if really needed
   VERSION_CLASSFILE_MAJOR="$DEFAULT_VERSION_CLASSFILE_MAJOR"
   VERSION_CLASSFILE_MINOR="$DEFAULT_VERSION_CLASSFILE_MINOR"
+  VERSION_DOCS_API_SINCE="$DEFAULT_VERSION_DOCS_API_SINCE"
   JDK_SOURCE_TARGET_VERSION="$DEFAULT_JDK_SOURCE_TARGET_VERSION"
 
   AC_MSG_CHECKING([for version string])
@@ -557,5 +558,6 @@ AC_DEFUN_ONCE([JDKVER_SETUP_JDK_VERSION_NUMBERS],
   AC_SUBST(VENDOR_VERSION_STRING)
   AC_SUBST(VERSION_CLASSFILE_MAJOR)
   AC_SUBST(VERSION_CLASSFILE_MINOR)
+  AC_SUBST(VERSION_DOCS_API_SINCE)
   AC_SUBST(JDK_SOURCE_TARGET_VERSION)
 ])

make/autoconf/spec.gmk.in

@@ -230,6 +230,9 @@ VENDOR_VERSION_STRING := @VENDOR_VERSION_STRING@
 VERSION_CLASSFILE_MAJOR := @VERSION_CLASSFILE_MAJOR@
 VERSION_CLASSFILE_MINOR := @VERSION_CLASSFILE_MINOR@
 
+# Version for API docs "new-since" feature
+VERSION_DOCS_API_SINCE := @VERSION_DOCS_API_SINCE@
+
 JDK_SOURCE_TARGET_VERSION := @JDK_SOURCE_TARGET_VERSION@
 
 # Convenience CFLAGS settings for passing version information into native programs.

make/conf/version-numbers.conf

@@ -36,6 +36,7 @@ DEFAULT_VERSION_EXTRA3=0
 DEFAULT_VERSION_DATE=2021-09-14
 DEFAULT_VERSION_CLASSFILE_MAJOR=61  # "`$EXPR $DEFAULT_VERSION_FEATURE + 44`"
 DEFAULT_VERSION_CLASSFILE_MINOR=0
+DEFAULT_VERSION_DOCS_API_SINCE=11
 DEFAULT_ACCEPTABLE_BOOT_VERSIONS="16 17"
 DEFAULT_JDK_SOURCE_TARGET_VERSION=17
 DEFAULT_PROMOTED_VERSION_PRE=ea

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java

@@ -142,6 +142,8 @@ public class Contents {
     public final Content navProperty;
     public final Content navServices;
     public final Content nestedClassSummary;
+    public final Content newAPI;
+    public final Content newLabel;
     public final Content noScriptMessage;
     public final Content openModuleLabel;
     public final Content openedTo;
@@ -287,6 +289,8 @@ public class Contents {
         navProperty = getContent("doclet.navProperty");
         navServices = getContent("doclet.navServices");
         nestedClassSummary = getContent("doclet.Nested_Class_Summary");
+        newAPI = getContent("doclet.New_API");
+        newLabel = getContent("doclet.New_Label");
         noScriptMessage = getContent("doclet.No_Script_Message");
         openedTo = getContent("doclet.OpenedTo");
         openModuleLabel = getContent("doclet.Open_Module");

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java

@@ -27,8 +27,11 @@
 
 import com.sun.source.doctree.DeprecatedTree;
 import java.util.List;
+import java.util.ListIterator;
 
 import javax.lang.model.element.Element;
+
+import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
 import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
 import jdk.javadoc.internal.doclets.toolkit.Content;
@@ -45,18 +48,17 @@
  *  If you write code that depends on this, you do so at your own risk.
  *  This code and its internal interfaces are subject to change or
  *  deletion without notice.</b>
- *
- * @see java.util.List
  */
 public class DeprecatedListWriter extends SummaryListWriter<DeprecatedAPIListBuilder> {
 
+    private final static String TERMINALLY_DEPRECATED_KEY = "doclet.Terminally_Deprecated_Elements";
+
     /**
      * Constructor.
      *
      * @param configuration the configuration for this doclet
      * @param filename the file to be generated
      */
-
     public DeprecatedListWriter(HtmlConfiguration configuration, DocPath filename) {
         super(configuration, filename, PageMode.DEPRECATED, "deprecated elements",
               configuration.contents.deprecatedAPI, "doclet.Window_Deprecated_List");
@@ -80,17 +82,22 @@ public static void generate(HtmlConfiguration configuration) throws DocFileIOExc
 
     @Override
     protected void addExtraSection(DeprecatedAPIListBuilder list, Content content) {
+        if (list.releases.size() > 1) {
+            content.add(HtmlTree.SPAN(contents.getContent("doclet.Deprecated_Tabs_Intro"))
+                    .addStyle(HtmlStyle.helpNote));
+        }
         addSummaryAPI(list.getForRemoval(), HtmlIds.FOR_REMOVAL,
-                    "doclet.For_Removal", "doclet.Element", content);
+                    TERMINALLY_DEPRECATED_KEY, "doclet.Element", content);
     }
 
     @Override
     protected void addExtraIndexLink(DeprecatedAPIListBuilder list, Content target) {
         if (!list.getForRemoval().isEmpty()) {
-            addIndexLink(HtmlIds.FOR_REMOVAL, "doclet.For_Removal", target);
+            addIndexLink(HtmlIds.FOR_REMOVAL, "doclet.Terminally_Deprecated", target);
         }
     }
 
+    @Override
     protected void addComments(Element e, Content desc) {
         List<? extends DeprecatedTree> tags = utils.getDeprecatedTrees(e);
         if (!tags.isEmpty()) {
@@ -100,4 +107,28 @@ protected void addComments(Element e, Content desc) {
         }
     }
 
+    @Override
+    protected void addTableTabs(Table table, String headingKey) {
+        List<String> releases = configuration.deprecatedAPIListBuilder.releases;
+        if (!releases.isEmpty()) {
+            table.setDefaultTab(getTableCaption(headingKey)).setAlwaysShowDefaultTab(true);
+            ListIterator<String> it = releases.listIterator(releases.size());
+            while (it.hasPrevious()) {
+                String release = it.previous();
+                Content tab = TERMINALLY_DEPRECATED_KEY.equals(headingKey)
+                        ? contents.getContent("doclet.Terminally_Deprecated_In_Release", release)
+                        : contents.getContent("doclet.Deprecated_In_Release", release);
+                table.addTab(tab,
+                        element -> release.equals(utils.getDeprecatedSince(element)));
+            }
+            getMainBodyScript().append(table.getScript());
+        }
+    }
+
+    @Override
+    protected Content getTableCaption(String headingKey) {
+        Content caption = contents.getContent(headingKey);
+        return TERMINALLY_DEPRECATED_KEY.equals(headingKey)
+                ? caption : contents.getContent("doclet.Deprecated_Elements", caption);
+    }
 }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java

@@ -346,15 +346,6 @@ private Content getPageKindSection(HtmlTree mainTOC) {
             pageKindsSection.add(section);
         }
 
-        // Deprecated
-        if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
-            section = newHelpSection(contents.deprecatedAPI, PageMode.DEPRECATED, subTOC);
-            Content deprBody = getContent("doclet.help.deprecated.body",
-                    links.createLink(DocPaths.DEPRECATED_LIST, resources.getText("doclet.Deprecated_API")));
-            section.add(HtmlTree.P(deprBody));
-            pageKindsSection.add(section);
-        }
-
         // Preview
         if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
             section = newHelpSection(contents.previewAPI, PageMode.PREVIEW, subTOC);
@@ -364,6 +355,24 @@ private Content getPageKindSection(HtmlTree mainTOC) {
             pageKindsSection.add(section);
         }
 
+        // New
+        if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.NEW)) {
+            section = newHelpSection(contents.newAPI, PageMode.NEW, subTOC);
+            Content newBody = getContent("doclet.help.new.body",
+                    links.createLink(DocPaths.NEW_LIST, contents.newAPI));
+            section.add(HtmlTree.P(newBody));
+            pageKindsSection.add(section);
+        }
+
+        // Deprecated
+        if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
+            section = newHelpSection(contents.deprecatedAPI, PageMode.DEPRECATED, subTOC);
+            Content deprBody = getContent("doclet.help.deprecated.body",
+                    links.createLink(DocPaths.DEPRECATED_LIST, resources.getText("doclet.Deprecated_API")));
+            section.add(HtmlTree.P(deprBody));
+            pageKindsSection.add(section);
+        }
+
         // Constant Field Values
         if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.CONSTANT_VALUES)) {
             section = newHelpSection(contents.constantsSummaryTitle, PageMode.CONSTANT_VALUES, subTOC);

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java

@@ -60,6 +60,7 @@
 import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
+import jdk.javadoc.internal.doclets.toolkit.util.NewAPIBuilder;
 import jdk.javadoc.internal.doclets.toolkit.util.PreviewAPIListBuilder;
 
 /**
@@ -128,6 +129,14 @@ public class HtmlConfiguration extends BaseConfiguration {
      */
     protected PreviewAPIListBuilder previewAPIListBuilder;
 
+    /**
+     * The collection of new API items, if any, to be displayed on the new-list page,
+     * or null if the page should not be generated.
+     * The page is only generated if the {@code --since} option is used with release
+     * names matching {@code @since} tags in the documented code.
+     */
+    protected NewAPIBuilder newAPIPageBuilder;
+
     public Contents contents;
 
     protected final Messages messages;
@@ -146,7 +155,7 @@ public class HtmlConfiguration extends BaseConfiguration {
     // Note: this should (eventually) be merged with Navigation.PageMode,
     // which performs a somewhat similar role
     public enum ConditionalPage {
-        CONSTANT_VALUES, DEPRECATED, PREVIEW, SERIALIZED_FORM, SYSTEM_PROPERTIES
+        CONSTANT_VALUES, DEPRECATED, PREVIEW, SERIALIZED_FORM, SYSTEM_PROPERTIES, NEW
     }
 
     /**

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java

@@ -55,6 +55,7 @@
 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
 import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder;
+import jdk.javadoc.internal.doclets.toolkit.util.NewAPIBuilder;
 import jdk.javadoc.internal.doclets.toolkit.util.PreviewAPIListBuilder;
 
 /**
@@ -173,18 +174,25 @@ protected Function<String, String> getResourceKeyMapper(DocletEnvironment docEnv
 
     @Override // defined by AbstractDoclet
     public void generateClassFiles(ClassTree classTree) throws DocletException {
-
+        List<String> since = configuration.getOptions().since();
         if (!(configuration.getOptions().noDeprecated()
                 || configuration.getOptions().noDeprecatedList())) {
-            DeprecatedAPIListBuilder builder = new DeprecatedAPIListBuilder(configuration);
-            if (!builder.isEmpty()) {
-                configuration.deprecatedAPIListBuilder = builder;
+            DeprecatedAPIListBuilder deprecatedBuilder = new DeprecatedAPIListBuilder(configuration, since);
+            if (!deprecatedBuilder.isEmpty()) {
+                configuration.deprecatedAPIListBuilder = deprecatedBuilder;
                 configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.DEPRECATED);
             }
         }
-        PreviewAPIListBuilder builder = new PreviewAPIListBuilder(configuration);
-        if (!builder.isEmpty()) {
-            configuration.previewAPIListBuilder = builder;
+        if (!since.isEmpty()) {
+            NewAPIBuilder newAPIBuilder = new NewAPIBuilder(configuration, since);
+            if (!newAPIBuilder.isEmpty()) {
+                configuration.newAPIPageBuilder = newAPIBuilder;
+                configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.NEW);
+            }
+        }
+        PreviewAPIListBuilder previewBuilder = new PreviewAPIListBuilder(configuration);
+        if (!previewBuilder.isEmpty()) {
+            configuration.previewAPIListBuilder = previewBuilder;
             configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.PREVIEW);
         }
 
@@ -239,6 +247,10 @@ protected void generateOtherFiles(ClassTree classtree)
             PreviewListWriter.generate(configuration);
         }
 
+        if (configuration.conditionalPages.contains((HtmlConfiguration.ConditionalPage.NEW))) {
+            NewAPIListWriter.generate(configuration);
+        }
+
         if (options.createOverview()) {
             if (configuration.showModules) {
                 ModuleIndexWriter.generate(configuration);

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

@@ -2103,7 +2103,8 @@ public HtmlStyle getBodyStyle() {
         String kind = getClass().getSimpleName()
                 .replaceAll("(Writer)?(Impl)?$", "")
                 .replaceAll("AnnotationType", "Class")
-                .replaceAll("^(Module|Package|Class)$", "$1Declaration");
+                .replaceAll("^(Module|Package|Class)$", "$1Declaration")
+                .replace("API", "Api");
         String page = kind.substring(0, 1).toLowerCase(Locale.US) + kind.substring(1) + "Page";
         return HtmlStyle.valueOf(page);
     }