JDK-8263468: New page for "recent" new API #4209

hns · 2021-05-26T16:02:29Z

This adds a new kind of summary list for new API added in specific releases, and adds information to the deprecated API list about elements that were deprecated in the given releases.

The changes to the code are relatively minor thanks to the existing infrastructure for summary list pages, which was extended by adding the getTableCaption and addTableTabs methods to SummaryListWriter.java in order to generate tabbed tables.

One important area that needs to be reviewed is the addition of resources in standard.properties. A relatively big share of discussion and effort went into shaping the UI messages.

The build system change adds options to generate API changes for all releases after JDK 11, with "New API since JDK 11" as page title for the new API page. I uploaded the generated documentation here:

http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/new-list.html
http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/deprecated-list.html

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

JDK-8263468: New page for "recent" new API

Reviewers

Erik Joelsson (@erikj79 - Reviewer) ⚠️ Review applies to 2a9dbbb
Jonathan Gibbons (@jonathan-gibbons - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/4209/head:pull/4209
$ git checkout pull/4209

Update a local copy of the PR:
$ git checkout pull/4209
$ git pull https://git.openjdk.java.net/jdk pull/4209/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 4209

View PR using the GUI difftool:
$ git pr show -t 4209

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/4209.diff

# Conflicts: # src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css

bridgekeeper · 2021-05-26T16:03:42Z

👋 Welcome back hannesw! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2021-05-26T16:05:34Z

@hns The following labels will be automatically applied to this pull request:

build
javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

mlbridge · 2021-05-27T11:02:16Z

Webrevs

erikj79 · 2021-05-27T12:52:34Z

make/Docs.gmk

@@ -332,6 +332,9 @@ 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 12,13,14,15,16,17 --since-label "New API since JDK 11"


How do you expect this to change as the JDK version is bumped? If there is an expected pattern, then maybe we should try to generate the list instead, so we don't need to manually update twice a year.

I don't have a solution for this problem. AFAIK there are a few things that have to be "bumped" manually between releases, and this would be yet another. Obviously not a great solution.

Yes, there are a few things, but in the build itself, we are down to a single config file today, so I would really appreciate if this could be figured out. I can provide the implementation for generating this, but I need to understand what the expected pattern is. From what I can see, it looks like $(sequence N, M) where N is the last LTS+1 and M is current JDK version. Then the string has "JDK N" in it. M is already well defined, so the only new input here is N, which we could move to the version numbers config file (make/conf/version-numbers.conf). Something like DEFAULT_VERSION_DOCS_API_SINCE=11. There is some additional boilerplate needed, and the sequence macro of course, but does this sound reasonable to you?

We actually have a sequence macro already, so generating the list can be done like this:

$(call CommaList,$(call sequence 12, 17))

Or if what you have is 11 and 17:

$(call CommaList, $(filter-out 11, $(call sequence 11, 17)))

Thanks for the help and for providing all the pieces, Erik! I just added a new commit and I think I got everything working.

mlbridge · 2021-05-28T04:09:40Z

Mailing list message from Jonathan Gibbons on javadoc-dev:

On 5/27/21 6:31 AM, Erik Joelsson wrote:

On Thu, 27 May 2021 13:05:27 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

make/Docs.gmk line 336:

334:
335: # Add summary pages for new/deprecated APIs in recent releases
336: $1_OPTIONS += --since 12,13,14,15,16,17 --since-label "New API since JDK 11"
How do you expect this to change as the JDK version is bumped? If there is an expected pattern, then maybe we should try to generate the list instead, so we don't need to manually update twice a year.
I don't have a solution for this problem. AFAIK there are a few things that have to be "bumped" manually between releases, and this would be yet another. Obviously not a great solution.
Yes, there are a few things, but in the build itself, we are down to a single config file today, so I would really appreciate if this could be figured out. I can provide the implementation for generating this, but I need to understand what the expected pattern is. From what I can see, it looks like $(sequence N, M) where N is the last LTS+1 and M is current JDK version. Then the string has "JDK N" in it. M is already well defined, so the only new input here is N, which we could move to the version numbers config file (make/conf/version-numbers.conf). Something like DEFAULT_VERSION_DOCS_API_SINCE=11. There is some additional boilerplate needed, and the sequence macro of course, but does this sound reasonable to you?

The ability to reduce the configuration down to a single number, like
DEFAULT_VERSION_DOCS_API_SINCE=11, seems like a good solution until we
think of anything better. The issue will be how long we stay with 11,
and what do we move to after that, and when?

-- Jon

mlbridge · 2021-05-28T04:09:42Z

Mailing list message from Jonathan Gibbons on javadoc-dev:

On 5/27/21 6:31 AM, Erik Joelsson wrote:

On Thu, 27 May 2021 13:05:27 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

make/Docs.gmk line 336:

334:
335: # Add summary pages for new/deprecated APIs in recent releases
336: $1_OPTIONS += --since 12,13,14,15,16,17 --since-label "New API since JDK 11"
How do you expect this to change as the JDK version is bumped? If there is an expected pattern, then maybe we should try to generate the list instead, so we don't need to manually update twice a year.
I don't have a solution for this problem. AFAIK there are a few things that have to be "bumped" manually between releases, and this would be yet another. Obviously not a great solution.
Yes, there are a few things, but in the build itself, we are down to a single config file today, so I would really appreciate if this could be figured out. I can provide the implementation for generating this, but I need to understand what the expected pattern is. From what I can see, it looks like $(sequence N, M) where N is the last LTS+1 and M is current JDK version. Then the string has "JDK N" in it. M is already well defined, so the only new input here is N, which we could move to the version numbers config file (make/conf/version-numbers.conf). Something like DEFAULT_VERSION_DOCS_API_SINCE=11. There is some additional boilerplate needed, and the sequence macro of course, but does this sound reasonable to you?

The ability to reduce the configuration down to a single number, like
DEFAULT_VERSION_DOCS_API_SINCE=11, seems like a good solution until we
think of anything better. The issue will be how long we stay with 11,
and what do we move to after that, and when?

-- Jon

erikj79

Build changes look great!

openjdk · 2021-05-28T12:43:08Z

@hns This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8263468: New page for "recent" new API

Reviewed-by: erikj, jjg

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 21 new commits pushed to the master branch:

159cb6f: 8268083: JDK-8267706 breaks bin/idea.sh on a Mac
8158b82: 8268327: Upstream: 8268169: The system lookup can not find stdio functions such as printf on Windows 10
6843576: 8268227: java/foreign/TestUpcall.java still times out
2717fcb: 8232948: javac -h should mangle the overload argument signature
89da202: 8266159: macOS ARM + Metal pipeline shows artifacts on Swing Menu with Java L&F
61ab4b9: 8267564: JDK-8252971 causes SPECjbb2015 socket exceptions on Windows when MKS is installed
00c88f7: 8266918: merge_stack in check_code.c add NULL check
8105478: 8268165: AsyncLogging will crash if rotate() fails
fd91b2a: 8265440: IGV: make node selection more visible
81bad59: 8257774: G1: Trigger collect when free region count drops below threshold to prevent evacuation failures
... and 11 more: https://git.openjdk.java.net/jdk/compare/3396b69fc91db4a9e29806562215f92179ba4757...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

jonathan-gibbons

Some minor suggestions for your consideration

jonathan-gibbons · 2021-06-07T14:52:57Z

...avadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties

+doclet.Deprecated_In_Release=Deprecated in {0}
+doclet.Deprecated_Tabs_Intro=(The leftmost tab "Deprecated ..." indicates all the \
+    deprecated elements, regardless of the releases in which they were deprecated. \
+    Each of the righthand tabs "Deprecated in ..." indicates the elements deprecated \


"Each of the righthand" doesn't read well. Would "Each of the other" be better?

Changed to "Each of the other".

jonathan-gibbons · 2021-06-07T14:53:13Z

...avadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties

+doclet.New_Elements_Added_In_Release=Added in {0}
+doclet.New_Label=New
+doclet.New_Tabs_Intro=(The leftmost tab "New ..." indicates all the new elements, \
+    regardless of the releases in which they were added. Each of the righthand \


jonathan-gibbons · 2021-06-07T14:53:55Z

...avadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties

@@ -245,6 +263,9 @@ doclet.help.deprecated.body=\
 doclet.help.preview.body=\
    The {0} page lists all of the Preview APIs. \
    Preview APIs may be removed in future implementations.
+doclet.help.new.body=\
+    The {0} page lists APIs that have been added in recent releases. \
+    The content of this page is based on information provided by Javadoc @since tags.


Either change to "JavaDoc" or (preferably?) just delete this word, or even the sentence.

Is there any interaction with -nosince? Should there be?

I removed the second sentence.

There is no interaction with -nosince. I one point I thought -nosince should disable this feature, but actually both features are just different ways of displaying the information stored in @since tags that don't depend on each other.

jonathan-gibbons · 2021-06-07T14:55:58Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java

-        assert SourceVersion.valueOf("RELEASE_" + versionNumber) == sourceVersion;
-        return Integer.parseInt(versionNumber);
+    public int getSourceVersionNumber() {
+        return configuration.docEnv.getSourceVersion().ordinal();


As a general comment, I believe Joe does not encourage use of ordinal

I undid this change as it's not really part of the feature.

jonathan-gibbons · 2021-06-07T15:27:21Z

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

+ * Generate File to list all the new API elements with the
+ * appropriate links.


(minor) not standard form of comment, but it's "only" an internal class, so could be fixed up later

This comment and the comment below was copied and adapter from another SummaryListWriter subclass. I took the liberty of rewriting both comments.

jonathan-gibbons · 2021-06-07T15:33:01Z

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

+    /**
+     * The class of the {@code body} element for the page listing any deprecated items.
+     */
+    deprecatedInReleasePage,
+


Note to self ... affects new "Output Generated ...." document

jonathan-gibbons · 2021-06-07T15:36:55Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocPaths.java

@@ -145,6 +145,9 @@ public static DocPath indexN(int n) {
    /** The name of the fie for preview elements. */
    public static final DocPath PREVIEW_LIST = DocPath.create("preview-list.html");

+    /** The name of the fie for new elements. */


jonathan-gibbons · 2021-06-07T15:37:13Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocPaths.java

@@ -145,6 +145,9 @@ public static DocPath indexN(int n) {
    /** The name of the fie for preview elements. */


typo: "fie"

jonathan-gibbons · 2021-06-07T15:41:01Z

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

+        return (String) getDeprecatedElement(e, "since");
+    }
+
+    // Returns the Deprecated annotation element value of the given element, or null.


Use /**...*/

jonathan-gibbons · 2021-06-07T15:46:45Z

test/langtools/jdk/javadoc/doclet/testNewApiList/mdl/module-info.java

+ */
+module mdl {
+    exports pkg;
+}


final newline

For all these "sample API" source files, they are OK, but another time, consider the use of possibly-custom builders, to generate these files dynamically. and to make for more concise reading.

jonathan-gibbons

One future suggestion.

jonathan-gibbons · 2021-06-08T16:16:27Z

...avadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties

+doclet.Deprecated_Tabs_Intro=(The leftmost tab "Deprecated ..." indicates all the \
+    deprecated elements, regardless of the releases in which they were deprecated. \
+    Each of the other tabs "Deprecated in ..." indicates the elements deprecated \
+    in a specific release.)


This is OK for now, but a noreg-doc follow-up might be to improve the punctuation in this text, possibly after consulting with docs folk.

It's the use of the quoted strings that seems weird, without any commas or parentheses too set them off. On the other hand, I realize we sometimes go for brevity in places like this.

hns · 2021-06-08T18:21:30Z

/integrate

openjdk · 2021-06-08T18:22:46Z

@hns Since your change was applied there have been 24 commits pushed to the master branch:

fafc4d9: 8268352: Rename javadoc Messager class to JavadocLog
b568e87: 8237388: serviceability/dcmd/framework/VMVersionTest.java fails with connection refused error.
c21cc93: 8248877: Document API contract for MetaspaceObj subtypes
159cb6f: 8268083: JDK-8267706 breaks bin/idea.sh on a Mac
8158b82: 8268327: Upstream: 8268169: The system lookup can not find stdio functions such as printf on Windows 10
6843576: 8268227: java/foreign/TestUpcall.java still times out
2717fcb: 8232948: javac -h should mangle the overload argument signature
89da202: 8266159: macOS ARM + Metal pipeline shows artifacts on Swing Menu with Java L&F
61ab4b9: 8267564: JDK-8252971 causes SPECjbb2015 socket exceptions on Windows when MKS is installed
00c88f7: 8266918: merge_stack in check_code.c add NULL check
... and 14 more: https://git.openjdk.java.net/jdk/compare/3396b69fc91db4a9e29806562215f92179ba4757...master

Your commit was automatically rebased without conflicts.

Pushed as commit dc6c96b.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

hns added 14 commits April 20, 2021 18:02

JDK-8263468: New page for "recent" new API

1f60f01

JDK-8263468: Use table tabs for releases instead of separate pages

a223ba1

JDK-8263468: Update wording and command line option

b3af620

JDK-8263468: Improve wording

9967180

JDK-8263468: Rename -since to --since, add --since-name option

a32e06d

JDK-8263468: Tweak help message wording

fbca1bc

JDK-8263468: Update to latest CSR

6690690

JDK-8263468: Fix tests

3f352cb

Merge branch 'master' into JDK-8263468

d3e0670

# Conflicts: # src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css

JDK-8263468: Update to new Table methods

b5ad15e

JDK-8263468: Add tests

e7c6cd8

JDK-8263468: Cleanup

30c477d

JDK-8263468: Remove unused DocPaths methods

956c4f6

JDK-8263468: make constant static

e81532b

openjdk bot added javadoc javadoc-dev@openjdk.org build build-dev@openjdk.org labels May 26, 2021

hns marked this pull request as ready for review May 27, 2021 10:57

openjdk bot added the rfr Pull request is ready for review label May 27, 2021

erikj79 reviewed May 27, 2021

View reviewed changes

JDK-8263468: automate build integration

2a9dbbb

erikj79 approved these changes May 28, 2021

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label May 28, 2021

Merge branch 'master' into JDK-8263468

3b13ae3

jonathan-gibbons reviewed Jun 7, 2021

View reviewed changes

JDK-8263468: review comments

c9c5f83

jonathan-gibbons approved these changes Jun 8, 2021

View reviewed changes

openjdk bot closed this Jun 8, 2021

openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jun 8, 2021

		* Generate File to list all the new API elements with the
		* appropriate links.

		@@ -145,6 +145,9 @@ public static DocPath indexN(int n) {
		/** The name of the fie for preview elements. */

JDK-8263468: New page for "recent" new API #4209

JDK-8263468: New page for "recent" new API #4209

Uh oh!

Conversation

hns commented May 26, 2021 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented May 26, 2021

Uh oh!

openjdk bot commented May 26, 2021

Uh oh!

mlbridge bot commented May 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erikj79 May 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mlbridge bot commented May 28, 2021

Uh oh!

mlbridge bot commented May 28, 2021

Uh oh!

erikj79 left a comment

Choose a reason for hiding this comment

Uh oh!

openjdk bot commented May 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonathan-gibbons left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonathan-gibbons left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hns commented Jun 8, 2021

hns commented May 26, 2021 •

edited by openjdk bot

Loading

mlbridge bot commented May 27, 2021 •

edited

Loading

erikj79 May 27, 2021 •

edited

Loading

openjdk bot commented May 28, 2021 •

edited

Loading