JDK-8254721: Improve support for conditionally generated files #674

jonathan-gibbons · 2020-10-15T00:31:51Z

The overall pages is very dynamic and depends on a lot of factors, such as the input files and the command-line options. Some of the summary files depend on the content of the classes being documented, such as:

any constant values declared in the files
any deprecated elements
any serializable classes
any classes whose description references system properties

This change is a step towards handling these files in a uniform manner.

There is a new test to test the consistency of the new behavior..

Progress

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

Testing

	Linux x64	Windows x64	macOS x64
Build	✔️ (5/5 passed)	✔️ (2/2 passed)	✔️ (2/2 passed)
Test (tier1)	✔️ (9/9 passed)	✔️ (9/9 passed)	✔️ (9/9 passed)

Issue

JDK-8254721: Improve support for conditionally generated files

Reviewers

Hannes Wallnöfer (@hns - Reviewer) ⚠️ Review applies to dbb0422

Download

$ git fetch https://git.openjdk.java.net/jdk pull/674/head:pull/674
$ git checkout pull/674

Improve support for conditionally generated files

bridgekeeper · 2020-10-15T00:32:25Z

👋 Welcome back jjg! 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 · 2020-10-15T00:34:20Z

@jonathan-gibbons The following label will be automatically applied to this pull request:

javadoc

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

mlbridge · 2020-10-17T00:00:16Z

Webrevs

01: Full - Incremental (3efdd95)
00: Full (dbb0422)

hns

Looks good, Jon. The inline comments all refer to minor issues.

hns · 2020-10-19T15:50:38Z

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

+        // System Properties
+        if (configuration.conditionalPages.contains(HtmlConfiguration.PageKind.SYSTEM_PROPERTIES)) {
+            section = newHelpSection(contents.systemPropertiesLabel);
+            Content constantsBody = getContent("doclet.help.systemProperties.body",


Not an actual problem, but constantsBody is the name used for the constant values page. Should be either a generic name or one hinting at the system properties content.

Good catch; will fix.

hns · 2020-10-19T15:50:38Z

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

+     */
+    // Note: this should (eventually) be merged with Navigation.PageMode,
+    // which performs a somewhat similar role
+    public enum PageKind {


Maybe call it ConditionalPage and change comment to "Kinds of conditional pages" to make purpose/scope clearer?

That would be a reasonable short term fix, but I was hoping to merge with Navigation.PageMode since both are enums for the different kinds of pages we generate. But I have not yet found the sweet spot for where to put this enum: it may be best for it to end up as a top-level enum in the formats.html package. Or, we avoid merging them, and rename PageKind as you suggest.

hns · 2020-10-19T15:50:38Z

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

-        depr.generateDeprecatedListFile(
-               new DeprecatedAPIListBuilder(configuration));
+        DeprecatedAPIListBuilder deprAPI = configuration.deprecatedAPIListBuilder;
+        if (deprAPI != null && !deprAPI.isEmpty()) {


Just a note regarding consistency: everywhere else you are using configuration.conditionalPages.contains(HtmlConfiguration.PageKind.DEPRECATED) for this check.

Yes, thanks; noted; I guess this is a hangover from before I added the PageKind.

openjdk · 2020-10-19T15:52:56Z

@jonathan-gibbons 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:

8254721: Improve support for conditionally generated files

Reviewed-by: hannesw

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 28 new commits pushed to the master branch:

14e1e17: 8255004: [JVMCI] expose JVM_ACC_FIELD_INITIALIZED_FINAL_UPDATE
f42c032: 8254793: [JVMCI] improve speculation encoding
74ac77e: 8247666: Support Lambda proxy classes in static CDS archive
e2e11d3: 8254955: x86: MethodHandlesAdapterBlob is too big
0b51016: 8253660: Need better error report when artifact resolution fails in AotCompiler.java
52cb329: 8254862: lldb in devkit doesn't work
60f63ec: 8254796: Cleanup pervasive unnecessary parameter
953e472: 8254967: com.sun.net.HttpsServer spins on TLS session close
1da28de: 8255009: delta apply fixes for JDK-8246774 and JDK-8253455, pushed too soon
a0382cd: 8253235: JFR.dump does not respect maxage parameter
... and 18 more: https://git.openjdk.java.net/jdk/compare/83ea863122e1d58527c8bf3cd178acf4d0c54f30...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 · 2020-10-19T20:50:14Z

Responded to all review feedback, and latest version builds and tests. Will integrate.

/integrate

openjdk · 2020-10-19T20:52:29Z

@jonathan-gibbons Since your change was applied there have been 29 commits pushed to the master branch:

0001435: 8255020: Minor updates to docs jdk.incubator.vector
14e1e17: 8255004: [JVMCI] expose JVM_ACC_FIELD_INITIALIZED_FINAL_UPDATE
f42c032: 8254793: [JVMCI] improve speculation encoding
74ac77e: 8247666: Support Lambda proxy classes in static CDS archive
e2e11d3: 8254955: x86: MethodHandlesAdapterBlob is too big
0b51016: 8253660: Need better error report when artifact resolution fails in AotCompiler.java
52cb329: 8254862: lldb in devkit doesn't work
60f63ec: 8254796: Cleanup pervasive unnecessary parameter
953e472: 8254967: com.sun.net.HttpsServer spins on TLS session close
1da28de: 8255009: delta apply fixes for JDK-8246774 and JDK-8253455, pushed too soon
... and 19 more: https://git.openjdk.java.net/jdk/compare/83ea863122e1d58527c8bf3cd178acf4d0c54f30...master

Your commit was automatically rebased without conflicts.

Pushed as commit cb5cdd7.

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

JDK-8254721

Loading status checks…

becdf2c

Improve support for conditionally generated files

jonathan-gibbons marked this pull request as draft Oct 15, 2020

openjdk bot added the javadoc label Oct 15, 2020

jonathan-gibbons added 2 commits Oct 15, 2020

fix trailing whitespace

Loading status checks…

fb83fd6

Merge master

Loading status checks…

dbb0422

jonathan-gibbons marked this pull request as ready for review Oct 16, 2020

openjdk bot added the rfr label Oct 16, 2020

hns approved these changes Oct 19, 2020

View changes

openjdk bot added the ready label Oct 19, 2020

Address minor review feedback

Loading status checks…

3efdd95

openjdk bot closed this Oct 19, 2020

openjdk bot added integrated and removed ready rfr labels Oct 19, 2020

jonathan-gibbons deleted the jonathan-gibbons:8254721-optional-pages branch Nov 4, 2020

openjdk / jdk

JDK-8254721: Improve support for conditionally generated files #674

JDK-8254721: Improve support for conditionally generated files #674

jonathan-gibbons commented Oct 15, 2020 •

edited by openjdk bot

bridgekeeper bot commented Oct 15, 2020

openjdk bot commented Oct 15, 2020

mlbridge bot commented Oct 17, 2020 •

edited

hns left a comment

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

openjdk bot commented Oct 19, 2020 •

edited

jonathan-gibbons commented Oct 19, 2020

openjdk bot commented Oct 19, 2020

openjdk / jdk

JDK-8254721: Improve support for conditionally generated files #674

JDK-8254721: Improve support for conditionally generated files #674

Conversation

jonathan-gibbons commented Oct 15, 2020 • edited by openjdk bot

Progress

Testing

Issue

Reviewers

Download

bridgekeeper bot commented Oct 15, 2020

openjdk bot commented Oct 15, 2020

mlbridge bot commented Oct 17, 2020 • edited

Webrevs

hns left a comment

This comment has been minimized.

hns Oct 19, 2020 Member

This comment has been minimized.

jonathan-gibbons Oct 19, 2020 Author Contributor

This comment has been minimized.

hns Oct 19, 2020 Member

This comment has been minimized.

jonathan-gibbons Oct 19, 2020 Author Contributor

This comment has been minimized.

hns Oct 19, 2020 Member

This comment has been minimized.

jonathan-gibbons Oct 19, 2020 Author Contributor

openjdk bot commented Oct 19, 2020 • edited

jonathan-gibbons commented Oct 19, 2020

openjdk bot commented Oct 19, 2020

jonathan-gibbons commented Oct 15, 2020 •

edited by openjdk bot

mlbridge bot commented Oct 17, 2020 •

edited

hns Oct 19, 2020
Member

jonathan-gibbons Oct 19, 2020
Author Contributor

hns Oct 19, 2020
Member

jonathan-gibbons Oct 19, 2020
Author Contributor

hns Oct 19, 2020
Member

jonathan-gibbons Oct 19, 2020
Author Contributor

openjdk bot commented Oct 19, 2020 •

edited