RFR: JDK-8238437: Support separate locales for console messages and HTML content.

[Jonathan Gibbons]

Please review a change to use separate locales for messages written to 
the console and for content written in the generated HTML pages.

Background: although the command-line help is not very informative about 
how the -locale option is used, the man page is clear that it is clear 
that the option affects the generated documentation.

*Command-line help:*

     -locale <name>
                   Locale to be used, e.g. en_US or en_US_WIN

*Man page:*

`-locale` *name*
:   Specifies the locale that the `javadoc` tool uses when it generates
     documentation. The argument is the name of the locale, as described in
     `java.util.Locale` documentation, such as `en_US` (English, United 
States)
     or `en_US_WIN` (Windows variant).

With the proposed change, the -locale option only affects the generated 
documentation; it does not affect console output, which will use the 
default locale, in line with other JDK tools.


*The changes ...*

The core of the change is in HtmlConfiguration, which creates the 
resource bundles for the Messages object (used to generate console 
messages) and for Configuration.getResources(), which is used to get the 
resources for content in the generated output.  To clarify the 
distinction, BaseConfiguration.getResources is renamed to 
BaseConfiguration.getDocResources, to emphasise that it is to be used 
for resources in the generated documentation. This rename percolates 
through most of the other affected files.  The rename also highlighted 
some issues in HtmlOptions, which were using the low-level reporter and 
resources API to generate messaages, instead of using the Messages API.  
These have now been fixed.

*The tests ...*

There's a somewhat surprising test case in TestSearch, which was testing 
the search feature when using Japanese and Chinese locales. The primary 
part of these test cases seems to be that the locale setting does *not* 
affect the generated search index files, but perhaps as a control to 
verify the locale option is taking effect, the test cases also verify 
some of the output generated by javadoc. It's not clear how useful the 
test cases are, but rather than simply remove them, each one is split in 
two: one to set the default locale, and one to use the locale option.

The primary test update is the recently-new TestLocaleOption.java, which 
is updated to be able to test the use of the default locale and the 
locale option. The test is refactored a bit to share more of the common 
code for the different test cases.


*Additional work ...*

The command-line help and man page should be improved. The man page 
states that the -locale option should be first on the command line, 
which is no longer the case.
The change should probably have a release note.


-- Jon


JBS: https://bugs.openjdk.java.net/browse/JDK-8238437
Webrev: http://cr.openjdk.java.net/~jjg/8238437/webrev/



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200206/223c0a13/attachment.htm>