[MJAVADOC-751] No warnings for localized output

[sitepark-schaeper]

This PR offers a solution for ticket MJAVADOC-751.
When parsing the output of the javadoc executable the english locale is expected (see containsWarnings and isInformationalOutput). In order for these checks to work the locale should be forced to english.

Following this checklist to help us incorporate your
contribution quickly and easily:

• Make sure there is a JIRA issue filed
  for the change (usually before you start working on it). Trivial changes like typos do not
  require a JIRA issue. Your pull request should address just this issue, without
  pulling in other changes.
• Each commit in the pull request should have a meaningful subject line and body.
• Format the pull request title like [MJAVADOC-XXX] - Fixes bug in ApproximateQuantiles,
  where you replace MJAVADOC-XXX with the appropriate JIRA issue. Best practice
  is to use the JIRA issue title in the pull request title and in the first line of the
  commit message.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Run mvn clean verify -Prun-its to make sure basic checks pass. A more thorough check will
  be performed on your pull request automatically.

If your pull request is about ~20 lines of code you don't need to sign an
Individual Contributor License Agreement if you are unsure
please ask on the developers list.

To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
you have to acknowledge this by using the following check-box.

• I hereby declare this contribution to be licensed under the Apache License Version 2.0, January 2004

• In any other case, please file an Apache Individual Contributor License Agreement.

[elharo]

This needs a test.

This might be a temporary workaround, but longer term I wonder if there's a non-command line way to invoke Javadoc these days.

[sitepark-schaeper]

This needs a test.

How would one go about testing this? Do we execute a test that executes the javadoc executable and check wether the output is english? There would also have to be a german/japanese/chinese environment to execute this test in as doing so in only english environments seems redundant.

This might be a temporary workaround, but longer term I wonder if there's a non-command line way to invoke Javadoc these days.

In Java 8 it should be as easy as:

javax.tools.ToolProvider.getSystemDocumentationTool().run(in, out, err, args)

And in Java 9+:

java.util.spi.ToolProvider.getSystemDocumentationTool().run(in, out, err, args);

But if we do that than we cannot influence the output locale anymore as it will always use Locale.default() (see here) and therefore cannot parse it reliably.

[michael-o]

Why not use -locale or use -J-D and so forth?

[michael-o]

I can confirm that -J-Duser.language=en works:

D:\Entwicklung\workspace-4.7\foo\target\site\apidocs>cmd.exe /X /C ""C:\Program Files\Eclipse Adoptium\jdk-21.0.3.9-hotspot\bin\javadoc.exe" @options @packages"
Quelldateien werden geladen für Package foo...
Javadoc-Informationen werden erstellt...
Fehler: Keine öffentlichen oder geschützten Klassen zur Dokumentation gefunden.
1 Fehler

with flag set:

D:\Entwicklung\workspace-4.7\foo\target\site\apidocs>cmd.exe /X /C ""C:\Program Files\Eclipse Adoptium\jdk-21.0.3.9-hotspot\bin\javadoc.exe" -J-Duser.language= @options @packages"
Loading source files for package foo...
Constructing Javadoc information...
error: No public or protected classes found to document.
1 error

[michael-o]

I have a potential fix. NEeds to be a separate issue. Unfortunately, there is not standard way to fix this.

[michael-o]

Affected locales: https://github.com/openjdk/jdk21u-dev/tree/master/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/resources

[michael-o]

Superseded by #298.

[sitepark-schaeper]

Thank you very much for fixing this!