Skip to content

Commit dc6c96b

Browse files
hnshns
committed
8263468: New page for "recent" new API
Reviewed-by: erikj, jjg
1 parent fafc4d9 commit dc6c96b

40 files changed

Lines changed: 1886 additions & 74 deletions

‎make/Docs.gmk‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,12 @@ define SetupApiDocsGenerationBody
332332
$$(eval $$(call create_overview_file,$1))
333333
$1_OPTIONS += -overview $$($1_OVERVIEW)
334334

335+
# Add summary pages for new/deprecated APIs in recent releases
336+
$1_OPTIONS += --since $(call CommaList, \
337+
$(filter-out $(VERSION_DOCS_API_SINCE), \
338+
$(call sequence, $(VERSION_DOCS_API_SINCE), $(VERSION_FEATURE))))
339+
$1_OPTIONS += --since-label "New API since JDK $(VERSION_DOCS_API_SINCE)"
340+
335341
$$(foreach g, $$($1_GROUPS), \
336342
$$(eval $1_OPTIONS += -group "$$($$g_GROUP_NAME)" "$$($$g_GROUP_MODULES)") \
337343
)

‎make/autoconf/jdk-version.m4‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -533,6 +533,7 @@ AC_DEFUN_ONCE([JDKVER_SETUP_JDK_VERSION_NUMBERS],
533533
# We could define --with flags for these, if really needed
534534
VERSION_CLASSFILE_MAJOR="$DEFAULT_VERSION_CLASSFILE_MAJOR"
535535
VERSION_CLASSFILE_MINOR="$DEFAULT_VERSION_CLASSFILE_MINOR"
536+
VERSION_DOCS_API_SINCE="$DEFAULT_VERSION_DOCS_API_SINCE"
536537
JDK_SOURCE_TARGET_VERSION="$DEFAULT_JDK_SOURCE_TARGET_VERSION"
537538
538539
AC_MSG_CHECKING([for version string])
@@ -557,5 +558,6 @@ AC_DEFUN_ONCE([JDKVER_SETUP_JDK_VERSION_NUMBERS],
557558
AC_SUBST(VENDOR_VERSION_STRING)
558559
AC_SUBST(VERSION_CLASSFILE_MAJOR)
559560
AC_SUBST(VERSION_CLASSFILE_MINOR)
561+
AC_SUBST(VERSION_DOCS_API_SINCE)
560562
AC_SUBST(JDK_SOURCE_TARGET_VERSION)
561563
])

‎make/autoconf/spec.gmk.in‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,9 @@ VENDOR_VERSION_STRING := @VENDOR_VERSION_STRING@
230230
VERSION_CLASSFILE_MAJOR := @VERSION_CLASSFILE_MAJOR@
231231
VERSION_CLASSFILE_MINOR := @VERSION_CLASSFILE_MINOR@
232232

233+
# Version for API docs "new-since" feature
234+
VERSION_DOCS_API_SINCE := @VERSION_DOCS_API_SINCE@
235+
233236
JDK_SOURCE_TARGET_VERSION := @JDK_SOURCE_TARGET_VERSION@
234237

235238
# Convenience CFLAGS settings for passing version information into native programs.

‎make/conf/version-numbers.conf‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ DEFAULT_VERSION_EXTRA3=0
3636
DEFAULT_VERSION_DATE=2021-09-14
3737
DEFAULT_VERSION_CLASSFILE_MAJOR=61 # "`$EXPR $DEFAULT_VERSION_FEATURE + 44`"
3838
DEFAULT_VERSION_CLASSFILE_MINOR=0
39+
DEFAULT_VERSION_DOCS_API_SINCE=11
3940
DEFAULT_ACCEPTABLE_BOOT_VERSIONS="16 17"
4041
DEFAULT_JDK_SOURCE_TARGET_VERSION=17
4142
DEFAULT_PROMOTED_VERSION_PRE=ea

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,8 @@ public class Contents {
142142
public final Content navProperty;
143143
public final Content navServices;
144144
public final Content nestedClassSummary;
145+
public final Content newAPI;
146+
public final Content newLabel;
145147
public final Content noScriptMessage;
146148
public final Content openModuleLabel;
147149
public final Content openedTo;
@@ -287,6 +289,8 @@ public class Contents {
287289
navProperty = getContent("doclet.navProperty");
288290
navServices = getContent("doclet.navServices");
289291
nestedClassSummary = getContent("doclet.Nested_Class_Summary");
292+
newAPI = getContent("doclet.New_API");
293+
newLabel = getContent("doclet.New_Label");
290294
noScriptMessage = getContent("doclet.No_Script_Message");
291295
openedTo = getContent("doclet.OpenedTo");
292296
openModuleLabel = getContent("doclet.Open_Module");

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

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,11 @@
2727

2828
import com.sun.source.doctree.DeprecatedTree;
2929
import java.util.List;
30+
import java.util.ListIterator;
3031

3132
import javax.lang.model.element.Element;
33+
34+
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
3235
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
3336
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
3437
import jdk.javadoc.internal.doclets.toolkit.Content;
@@ -45,18 +48,17 @@
4548
* If you write code that depends on this, you do so at your own risk.
4649
* This code and its internal interfaces are subject to change or
4750
* deletion without notice.</b>
48-
*
49-
* @see java.util.List
5051
*/
5152
public class DeprecatedListWriter extends SummaryListWriter<DeprecatedAPIListBuilder> {
5253

54+
private final static String TERMINALLY_DEPRECATED_KEY = "doclet.Terminally_Deprecated_Elements";
55+
5356
/**
5457
* Constructor.
5558
*
5659
* @param configuration the configuration for this doclet
5760
* @param filename the file to be generated
5861
*/
59-
6062
public DeprecatedListWriter(HtmlConfiguration configuration, DocPath filename) {
6163
super(configuration, filename, PageMode.DEPRECATED, "deprecated elements",
6264
configuration.contents.deprecatedAPI, "doclet.Window_Deprecated_List");
@@ -80,17 +82,22 @@ public static void generate(HtmlConfiguration configuration) throws DocFileIOExc
8082

8183
@Override
8284
protected void addExtraSection(DeprecatedAPIListBuilder list, Content content) {
85+
if (list.releases.size() > 1) {
86+
content.add(HtmlTree.SPAN(contents.getContent("doclet.Deprecated_Tabs_Intro"))
87+
.addStyle(HtmlStyle.helpNote));
88+
}
8389
addSummaryAPI(list.getForRemoval(), HtmlIds.FOR_REMOVAL,
84-
"doclet.For_Removal", "doclet.Element", content);
90+
TERMINALLY_DEPRECATED_KEY, "doclet.Element", content);
8591
}
8692

8793
@Override
8894
protected void addExtraIndexLink(DeprecatedAPIListBuilder list, Content target) {
8995
if (!list.getForRemoval().isEmpty()) {
90-
addIndexLink(HtmlIds.FOR_REMOVAL, "doclet.For_Removal", target);
96+
addIndexLink(HtmlIds.FOR_REMOVAL, "doclet.Terminally_Deprecated", target);
9197
}
9298
}
9399

100+
@Override
94101
protected void addComments(Element e, Content desc) {
95102
List<? extends DeprecatedTree> tags = utils.getDeprecatedTrees(e);
96103
if (!tags.isEmpty()) {
@@ -100,4 +107,28 @@ protected void addComments(Element e, Content desc) {
100107
}
101108
}
102109

110+
@Override
111+
protected void addTableTabs(Table table, String headingKey) {
112+
List<String> releases = configuration.deprecatedAPIListBuilder.releases;
113+
if (!releases.isEmpty()) {
114+
table.setDefaultTab(getTableCaption(headingKey)).setAlwaysShowDefaultTab(true);
115+
ListIterator<String> it = releases.listIterator(releases.size());
116+
while (it.hasPrevious()) {
117+
String release = it.previous();
118+
Content tab = TERMINALLY_DEPRECATED_KEY.equals(headingKey)
119+
? contents.getContent("doclet.Terminally_Deprecated_In_Release", release)
120+
: contents.getContent("doclet.Deprecated_In_Release", release);
121+
table.addTab(tab,
122+
element -> release.equals(utils.getDeprecatedSince(element)));
123+
}
124+
getMainBodyScript().append(table.getScript());
125+
}
126+
}
127+
128+
@Override
129+
protected Content getTableCaption(String headingKey) {
130+
Content caption = contents.getContent(headingKey);
131+
return TERMINALLY_DEPRECATED_KEY.equals(headingKey)
132+
? caption : contents.getContent("doclet.Deprecated_Elements", caption);
133+
}
103134
}

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

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -346,15 +346,6 @@ private Content getPageKindSection(HtmlTree mainTOC) {
346346
pageKindsSection.add(section);
347347
}
348348

349-
// Deprecated
350-
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
351-
section = newHelpSection(contents.deprecatedAPI, PageMode.DEPRECATED, subTOC);
352-
Content deprBody = getContent("doclet.help.deprecated.body",
353-
links.createLink(DocPaths.DEPRECATED_LIST, resources.getText("doclet.Deprecated_API")));
354-
section.add(HtmlTree.P(deprBody));
355-
pageKindsSection.add(section);
356-
}
357-
358349
// Preview
359350
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
360351
section = newHelpSection(contents.previewAPI, PageMode.PREVIEW, subTOC);
@@ -364,6 +355,24 @@ private Content getPageKindSection(HtmlTree mainTOC) {
364355
pageKindsSection.add(section);
365356
}
366357

358+
// New
359+
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.NEW)) {
360+
section = newHelpSection(contents.newAPI, PageMode.NEW, subTOC);
361+
Content newBody = getContent("doclet.help.new.body",
362+
links.createLink(DocPaths.NEW_LIST, contents.newAPI));
363+
section.add(HtmlTree.P(newBody));
364+
pageKindsSection.add(section);
365+
}
366+
367+
// Deprecated
368+
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
369+
section = newHelpSection(contents.deprecatedAPI, PageMode.DEPRECATED, subTOC);
370+
Content deprBody = getContent("doclet.help.deprecated.body",
371+
links.createLink(DocPaths.DEPRECATED_LIST, resources.getText("doclet.Deprecated_API")));
372+
section.add(HtmlTree.P(deprBody));
373+
pageKindsSection.add(section);
374+
}
375+
367376
// Constant Field Values
368377
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.CONSTANT_VALUES)) {
369378
section = newHelpSection(contents.constantsSummaryTitle, PageMode.CONSTANT_VALUES, subTOC);

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

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@
6060
import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
6161
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
6262
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
63+
import jdk.javadoc.internal.doclets.toolkit.util.NewAPIBuilder;
6364
import jdk.javadoc.internal.doclets.toolkit.util.PreviewAPIListBuilder;
6465

6566
/**
@@ -128,6 +129,14 @@ public class HtmlConfiguration extends BaseConfiguration {
128129
*/
129130
protected PreviewAPIListBuilder previewAPIListBuilder;
130131

132+
/**
133+
* The collection of new API items, if any, to be displayed on the new-list page,
134+
* or null if the page should not be generated.
135+
* The page is only generated if the {@code --since} option is used with release
136+
* names matching {@code @since} tags in the documented code.
137+
*/
138+
protected NewAPIBuilder newAPIPageBuilder;
139+
131140
public Contents contents;
132141

133142
protected final Messages messages;
@@ -146,7 +155,7 @@ public class HtmlConfiguration extends BaseConfiguration {
146155
// Note: this should (eventually) be merged with Navigation.PageMode,
147156
// which performs a somewhat similar role
148157
public enum ConditionalPage {
149-
CONSTANT_VALUES, DEPRECATED, PREVIEW, SERIALIZED_FORM, SYSTEM_PROPERTIES
158+
CONSTANT_VALUES, DEPRECATED, PREVIEW, SERIALIZED_FORM, SYSTEM_PROPERTIES, NEW
150159
}
151160

152161
/**

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

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@
5555
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
5656
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
5757
import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder;
58+
import jdk.javadoc.internal.doclets.toolkit.util.NewAPIBuilder;
5859
import jdk.javadoc.internal.doclets.toolkit.util.PreviewAPIListBuilder;
5960

6061
/**
@@ -173,18 +174,25 @@ protected Function<String, String> getResourceKeyMapper(DocletEnvironment docEnv
173174

174175
@Override // defined by AbstractDoclet
175176
public void generateClassFiles(ClassTree classTree) throws DocletException {
176-
177+
List<String> since = configuration.getOptions().since();
177178
if (!(configuration.getOptions().noDeprecated()
178179
|| configuration.getOptions().noDeprecatedList())) {
179-
DeprecatedAPIListBuilder builder = new DeprecatedAPIListBuilder(configuration);
180-
if (!builder.isEmpty()) {
181-
configuration.deprecatedAPIListBuilder = builder;
180+
DeprecatedAPIListBuilder deprecatedBuilder = new DeprecatedAPIListBuilder(configuration, since);
181+
if (!deprecatedBuilder.isEmpty()) {
182+
configuration.deprecatedAPIListBuilder = deprecatedBuilder;
182183
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.DEPRECATED);
183184
}
184185
}
185-
PreviewAPIListBuilder builder = new PreviewAPIListBuilder(configuration);
186-
if (!builder.isEmpty()) {
187-
configuration.previewAPIListBuilder = builder;
186+
if (!since.isEmpty()) {
187+
NewAPIBuilder newAPIBuilder = new NewAPIBuilder(configuration, since);
188+
if (!newAPIBuilder.isEmpty()) {
189+
configuration.newAPIPageBuilder = newAPIBuilder;
190+
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.NEW);
191+
}
192+
}
193+
PreviewAPIListBuilder previewBuilder = new PreviewAPIListBuilder(configuration);
194+
if (!previewBuilder.isEmpty()) {
195+
configuration.previewAPIListBuilder = previewBuilder;
188196
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.PREVIEW);
189197
}
190198

@@ -239,6 +247,10 @@ protected void generateOtherFiles(ClassTree classtree)
239247
PreviewListWriter.generate(configuration);
240248
}
241249

250+
if (configuration.conditionalPages.contains((HtmlConfiguration.ConditionalPage.NEW))) {
251+
NewAPIListWriter.generate(configuration);
252+
}
253+
242254
if (options.createOverview()) {
243255
if (configuration.showModules) {
244256
ModuleIndexWriter.generate(configuration);

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2103,7 +2103,8 @@ public HtmlStyle getBodyStyle() {
21032103
String kind = getClass().getSimpleName()
21042104
.replaceAll("(Writer)?(Impl)?$", "")
21052105
.replaceAll("AnnotationType", "Class")
2106-
.replaceAll("^(Module|Package|Class)$", "$1Declaration");
2106+
.replaceAll("^(Module|Package|Class)$", "$1Declaration")
2107+
.replace("API", "Api");
21072108
String page = kind.substring(0, 1).toLowerCase(Locale.US) + kind.substring(1) + "Page";
21082109
return HtmlStyle.valueOf(page);
21092110
}

0 commit comments

Comments
 (0)