JDK-8247994: Localize javadoc search #16

jonathan-gibbons · 2020-12-13T00:19:59Z

This is for JDK16, as a precursor to fixing JDK-8258002.

While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.

The source file search.js is renamed to search.js.template, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.

Progress

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

Issue

JDK-8247994: Localize javadoc search

Reviewers

Hannes Wallnöfer (@hns - Reviewer)
Magnus Ihse Bursie (@magicus - Reviewer) ⚠️ Review applies to 8eb7f27

Download

$ git fetch https://git.openjdk.java.net/jdk16 pull/16/head:pull/16
$ git checkout pull/16

bridgekeeper · 2020-12-13T00:20:40Z

👋 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-12-13T00:21:29Z

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

build
compiler
core-libs
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.

jonathan-gibbons · 2020-12-13T00:22:04Z

make/CompileInterimLangtools.gmk

@@ -74,7 +74,7 @@ define SetupInterimModule
      EXCLUDE_FILES := $(TOPDIR)/src/$1/share/classes/module-info.java \
          Standard.java, \
      EXTRA_FILES := $(BUILDTOOLS_OUTPUTDIR)/gensrc/$1.interim/module-info.java, \
-      COPY := .gif .png .xml .css .js .txt javax.tools.JavaCompilerTool, \
+      COPY := .gif .png .xml .css .js .js.template .txt javax.tools.JavaCompilerTool, \


Build-folk: it would be nice if this macro could use $(jdk.javadoc_COPY) instead of having to duplicate entries.
(Future RFE?)

I agree. The entire design of CompileJavaModules.gmk needs to be updated. I've been procrastinating on cleaning this up, maybe it's time to get going on it...

mlbridge · 2020-12-13T00:25:06Z

Webrevs

hns

Looks good in general. <Unnamed> shouldn't be localized as it is an internal tag (see inline comment).

hns · 2020-12-14T09:11:31Z

...javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/search.js.template

 var highlight = "<span class=\"result-highlight\">$&</span>";
 var searchPattern = "";
 var fallbackPattern = "";
 var RANKING_THRESHOLD = 2;
 var NO_MATCH = 0xffff;
 var MIN_RESULTS = 3;
 var MAX_RESULTS = 500;
-var UNNAMED = "<Unnamed>";
+var UNNAMED = "##REPLACE:doclet.search.unnamed##";


<Unnamed> is not a string that is ever shown to the user, it is what is used by javadoc to denote the default package (see toolkit.util.DocletConstants.DEFAULT_PACKAGE_NAME). This variable shouldn't be localized as that would break behaviour for code in the default package (and show the localized string as package name, instead of no package name).

Noted, thanks

hns · 2020-12-14T09:34:31Z

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

+            try {
+                sb.append(resources.getText(m.group("key")));
+            } catch (MissingResourceException e) {
+                sb.append(m.group());


Shouldn't we propagate an error here, or issue a warning? If a key is missing localized properties the value from default properties should be used, so this should never happen, right?

I see the added check for "##REPLACE:" in TestSearch.java will catch that case, so I guess it's ok.

magicus

Build changes look good.

magicus · 2020-12-15T09:23:52Z

make/CompileInterimLangtools.gmk

@@ -74,7 +74,7 @@ define SetupInterimModule
      EXCLUDE_FILES := $(TOPDIR)/src/$1/share/classes/module-info.java \
          Standard.java, \
      EXTRA_FILES := $(BUILDTOOLS_OUTPUTDIR)/gensrc/$1.interim/module-info.java, \
-      COPY := .gif .png .xml .css .js .txt javax.tools.JavaCompilerTool, \
+      COPY := .gif .png .xml .css .js .js.template .txt javax.tools.JavaCompilerTool, \


I agree. The entire design of CompileJavaModules.gmk needs to be updated. I've been procrastinating on cleaning this up, maybe it's time to get going on it...

openjdk · 2020-12-15T09:25:24Z

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

8247994: Localize javadoc search

Reviewed-by: hannesw, ihse

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

61cbf0f: 8258293: tools/jpackage/share/RuntimePackageTest.java#id0 with RuntimePackageTest.testUsrInstallDir2
7aac4dc: 8257621: JFR StringPool misses cached items across consecutive recordings
61390d8: 8257999: Parallel GC crash in gc/parallel/TestDynShrinkHeap.java: new region is not in covered_region
952dc70: 8257636: Update usage of "type" terminology in java.lang.Class and java.lang.reflect
04a1e5b: 8258505: [TESTBUG] TestDivZeroWithSplitIf.java fails due to missing UnlockDiagnosticVMOptions
41f312e: 8254023: A module declaration is not allowed to be a target of an annotation that lacks an @target meta-annotation

Please see this link for an up-to-date comparison between the source branch of this pull request and the master branch.
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.

hns · 2020-12-17T17:03:26Z

...javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/search.js.template

@@ -37,7 +37,7 @@ var RANKING_THRESHOLD = 2;
 var NO_MATCH = 0xffff;
 var MIN_RESULTS = 3;
 var MAX_RESULTS = 500;
-var UNNAMED = "##REPLACE:doclet.search.unnamed##";
+var UNNAMED = "<Unnamed>>";


Oops, an additional closing angle bracket slipped there.

jonathan-gibbons · 2020-12-17T18:34:01Z

/integrate

openjdk · 2020-12-17T18:34:41Z

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

47c180d: 8258515: javac should issue an error if an annotation is nested in a local class or interface
cb5a6b1: 8258225: compiler/c2/cr6340864/TestIntVect.java runs faster in interpreter
61cbf0f: 8258293: tools/jpackage/share/RuntimePackageTest.java#id0 with RuntimePackageTest.testUsrInstallDir2
7aac4dc: 8257621: JFR StringPool misses cached items across consecutive recordings
61390d8: 8257999: Parallel GC crash in gc/parallel/TestDynShrinkHeap.java: new region is not in covered_region
952dc70: 8257636: Update usage of "type" terminology in java.lang.Class and java.lang.reflect
04a1e5b: 8258505: [TESTBUG] TestDivZeroWithSplitIf.java fails due to missing UnlockDiagnosticVMOptions
41f312e: 8254023: A module declaration is not allowed to be a target of an annotation that lacks an @target meta-annotation

Your commit was automatically rebased without conflicts.

Pushed as commit 30ca0a5.

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

JDK-8247994: Localize javadoc search

8eb7f27

openjdk bot added the rfr Pull request is ready for review label Dec 13, 2020

openjdk bot added javadoc javadoc-dev@openjdk.java.net build build-dev@openjdk.java.net core-libs core-libs-dev@openjdk.java.net compiler compiler-dev@openjdk.java.net labels Dec 13, 2020

jonathan-gibbons commented Dec 13, 2020

View reviewed changes

hns suggested changes Dec 14, 2020

View reviewed changes

magicus approved these changes Dec 15, 2020

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Dec 15, 2020

jonathan-gibbons added 2 commits December 16, 2020 14:39

Merge remote-tracking branch 'upstream/master' into localize.search.js

ec11118

Address review comment

1a406f3

hns reviewed Dec 17, 2020

View reviewed changes

Address review comment

de6802c

hns approved these changes Dec 17, 2020

View reviewed changes

openjdk bot closed this Dec 17, 2020

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 Dec 17, 2020

Wanghuang-Huawei mentioned this pull request Jan 4, 2021

8259044： JVM lacks data type qualifier when using -XX:+PrintAssembly with AArch64-Neon backend #77

Closed

3 tasks

JDK-8247994: Localize javadoc search #16

JDK-8247994: Localize javadoc search #16

jonathan-gibbons commented Dec 13, 2020 •

edited by openjdk bot

bridgekeeper bot commented Dec 13, 2020

openjdk bot commented Dec 13, 2020

jonathan-gibbons Dec 13, 2020 •

edited

magicus Dec 15, 2020

mlbridge bot commented Dec 13, 2020 •

edited

hns left a comment

hns Dec 14, 2020

jonathan-gibbons Dec 16, 2020

hns Dec 14, 2020

hns Dec 14, 2020

magicus left a comment

magicus Dec 15, 2020

openjdk bot commented Dec 15, 2020 •

edited

hns Dec 17, 2020

jonathan-gibbons commented Dec 17, 2020

openjdk bot commented Dec 17, 2020

JDK-8247994: Localize javadoc search #16

JDK-8247994: Localize javadoc search #16

Conversation

jonathan-gibbons commented Dec 13, 2020 • edited by openjdk bot

Progress

Issue

Reviewers

Download

bridgekeeper bot commented Dec 13, 2020

openjdk bot commented Dec 13, 2020

jonathan-gibbons Dec 13, 2020 • edited

Choose a reason for hiding this comment

magicus Dec 15, 2020

Choose a reason for hiding this comment

mlbridge bot commented Dec 13, 2020 • edited

Webrevs

hns left a comment

Choose a reason for hiding this comment

hns Dec 14, 2020

Choose a reason for hiding this comment

jonathan-gibbons Dec 16, 2020

Choose a reason for hiding this comment

hns Dec 14, 2020

Choose a reason for hiding this comment

hns Dec 14, 2020

Choose a reason for hiding this comment

magicus left a comment

Choose a reason for hiding this comment

magicus Dec 15, 2020

Choose a reason for hiding this comment

openjdk bot commented Dec 15, 2020 • edited

hns Dec 17, 2020

Choose a reason for hiding this comment

jonathan-gibbons commented Dec 17, 2020

openjdk bot commented Dec 17, 2020

jonathan-gibbons commented Dec 13, 2020 •

edited by openjdk bot

jonathan-gibbons Dec 13, 2020 •

edited

mlbridge bot commented Dec 13, 2020 •

edited

openjdk bot commented Dec 15, 2020 •

edited