From jonathan.gibbons at oracle.com Sat Feb 1 00:48:48 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 31 Jan 2020 16:48:48 -0800 Subject: RFR: JDK-8222793 Javadoc tool ignores "-locale" param and uses default locale for all messages and texts Message-ID: <0c3d08e5-7b49-096f-6c43-bd3d6a456d79@oracle.com> Please review a medium-small fix for a regression in the new doclet. The problem is that the -locale option is not being handled correctly, and is not taking effect as it should. [Note: for a while, I was confusing the issue with a related related of possibly using different locales for the console messages and the generated docs. This is not that one.] The root cause is that some doclet objects are being initialized either too early or in the wrong order. The fix is to address the order of initialization, which allowed some unexpected additional cleanup. The locale option is picked up in the first pass over the options in Start, which determines the doclet and locale. After that first pass, the doclet is created and its init method called, passing in the locale. But, inside the doclet, the configuration object and some of its contents were created in the doclet's constructor, before the init method is called with the locale to use.? They end up seeing a null locale, which translates to the default locale. The fix is to delay initializing the configuration until the init method, which has the downside of making it not final, but the unexpected upside is that inside the configuration, a couple of lazy init methods can be removed, and the corresponding fields themselves made final. (So, net increase in final fields; yay!) The test is a bit tricky. We need to make sure that setting the -locale option correctly affects the various forms of generated output. But by default, the only locales we provide are asian and working with those Unicode characters can be challenging for some of us.? The solution is to generate a new set of resource files with similar-but-different content, and to install them in a different "test" locale.? Any easy conversion is to convert the values in the property files to upper case, and then to use another English locale, such as en_UK.? The easiest way to install new resource files is to use the --patch-module VM option, which means running javadoc in a child VM, which means we can't use the standard JavadocTester framework, which always uses same-vm mode. But, it's easy enough to use the toolbox library classes instead. The test runs javadoc a few times, with and without the -locale option, and verifies the generated text is coming from either the default resource bundle, or the uppercased resource bundle, as appropriate. The changeset has been tested on all standard platforms. -- Jon JBS: https://bugs.openjdk.java.net/browse/JDK-8222793 Webrev: http://cr.openjdk.java.net/~jjg/8222793/webrev/ From jonathan.gibbons at oracle.com Sun Feb 2 22:37:29 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Sun, 2 Feb 2020 14:37:29 -0800 Subject: RFR: JDK-8222793 Javadoc tool ignores "-locale" param and uses default locale for all messages and texts In-Reply-To: <0c3d08e5-7b49-096f-6c43-bd3d6a456d79@oracle.com> References: <0c3d08e5-7b49-096f-6c43-bd3d6a456d79@oracle.com> Message-ID: A couple of minor follow-ups. 1. ToolOptions has a ToolOption object for `-locale`, as it should (so that the option shows up in command-line help) but it sets a field `docLocale` with a corresponding accessor, which IIRC are unused.? They could be removed either in this changeset, or soon, perhaps with some improved comments in ToolOptions. 2. Another test case, that would more closely mirror the reported conditions for the error, would be to set a locale other than en_US as the default locale for javadoc, and then verify that using the `-locale en_US` option sets the locale correctly. -- Jon On 1/31/20 4:48 PM, Jonathan Gibbons wrote: > Please review a medium-small fix for a regression in the new doclet. > > The problem is that the -locale option is not being handled correctly, > and is not taking effect as it should. > > [Note: for a while, I was confusing the issue with a related related > of possibly using different locales for the console messages and the > generated docs. This is not that one.] > > The root cause is that some doclet objects are being initialized > either too early or in the wrong order. The fix is to address the > order of initialization, which allowed some unexpected additional > cleanup. > > The locale option is picked up in the first pass over the options in > Start, which determines the doclet and locale. After that first pass, > the doclet is created and its init method called, passing in the > locale. But, inside the doclet, the configuration object and some of > its contents were created in the doclet's constructor, before the init > method is called with the locale to use.? They end up seeing a null > locale, which translates to the default locale. > > The fix is to delay initializing the configuration until the init > method, which has the downside of making it not final, but the > unexpected upside is that inside the configuration, a couple of lazy > init methods can be removed, and the corresponding fields themselves > made final. (So, net increase in final fields; yay!) > > The test is a bit tricky. We need to make sure that setting the > -locale option correctly affects the various forms of generated > output. But by default, the only locales we provide are asian and > working with those Unicode characters can be challenging for some of > us.? The solution is to generate a new set of resource files with > similar-but-different content, and to install them in a different > "test" locale.? Any easy conversion is to convert the values in the > property files to upper case, and then to use another English locale, > such as en_UK.? The easiest way to install new resource files is to > use the --patch-module VM option, which means running javadoc in a > child VM, which means we can't use the standard JavadocTester > framework, which always uses same-vm mode. But, it's easy enough to > use the toolbox library classes instead. The test runs javadoc a few > times, with and without the -locale option, and verifies the generated > text is coming from either the default resource bundle, or the > uppercased resource bundle, as appropriate. > > The changeset has been tested on all standard platforms. > > -- Jon > > JBS: https://bugs.openjdk.java.net/browse/JDK-8222793 > Webrev: http://cr.openjdk.java.net/~jjg/8222793/webrev/ > > From jonathan.gibbons at oracle.com Mon Feb 3 19:06:59 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 3 Feb 2020 11:06:59 -0800 Subject: RFR [15] 8237909: Remove zipped index files feature In-Reply-To: References: Message-ID: I concur with all the preceding discussion, about removing the zipped-files feature, and about the desirability of asynchronous loading if that is practical. Separate RFE:? the UI should indicate if/while the results are incomplete. There's a TODO in AbstractIndexWriter.java 472 if (!searchIndex.isEmpty()) { // TODO: write to disk straight I'm pleased to see this line go: 318 tree.add(new RawHtml(" There's another, orthogonal, check in jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/script.js: if (window.navigator.userAgent.indexOf('MSIE ') > 0 || window.navigator.userAgent.indexOf('Trident/') > 0 || window.navigator.userAgent.indexOf('Edge/') > 0) { createElem(doc, tag, 'script-dir/jszip-utils/dist/jszip-utils-ie.js'); } While the former check loads the minified version of that JS library, the latter one loads the uncompressed version. Not that I'm concerned with the space or the size of the data transfers, those libs are tiny anyway, but this is just messy. If this changeset is pushed, this mess will go away. > We need a (separate?) plan of action for documenting this change and recommending that webservers delivering big API index files should be configured to use compression. Thinking. >> I intend to let this RFR sit here for at least 2 weeks. >> The perceived severity of this change should not be underestimated. > I think it is equally important to get this pushed early in the release, so that it can > be tested with real-world docs, such as the EA docs for JDK 15. I know. Let me try to come up with text for a release note, while this review is given a couple more days of sitting still. -Pavel --------------------------------- [1] https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/compatibility/hh801214(v=vs.85)?redirectedfrom=MSDN > > -- Jon > > > On 01/28/2020 07:55 AM, Pavel Rappo wrote: >> Hello, >> >> Please review the change for https://bugs.openjdk.java.net/browse/JDK-8237909 : >> >> http://cr.openjdk.java.net/~prappo/8237909/webrev.00/ >> >> This change removes the "zipped index files" feature, which was introduced as >> part of 8141492: Implement search feature in javadoc. >> >> The "zipped index files" feature consists of generating the zipped index files >> on the back end, and fetching & unzipping mechanics on the front end. >> >> When documenting source files, the standard doclet accumulates index which is >> later used by the JavaScript code serving the interactive search. The index >> is written in two formats, .js (JavaScript) and .json (JSON). The latter is >> then zipped. >> >> When a browser accesses the pages using "http://" urls, the .zip index files are >> transferred using XHR. Those files are then unzipped by the browser, using the >> JSZip library, and parsed as JSON. If the transfer of the .zip index files fails >> for whatever reason, the browser falls back on the alternative mechanism. This >> mechanism transfers the .js index files by referring to them from dynamically >> inserted