RFR: JDK-8260223: Handling of unnamed package in javadoc pages

[Hannes Wallnöfer]

This replaces the unlocalized `<Unnamed>` string with a localized string resource in API docs covering code in the unnamed package. The name used in the default locale is "Unnamed Package". The old `<Unnamed>` token is still used as an internal placeholder, for example in `Extern.java` and in the search index files.

Previously, we had two distinct `getPackageName(PackageElement)` methods, one in `HtmlDocletWriter` returning a Content object and one in `Utils` returning a String. The former is now changed to return the localized content resource. To disambiguate it from the latter, it is renamed to `getLocalizedPackageName`. I also added reciprocal references to the doc comments in both methods.

A few minor notes on changes that may not be obvious:

 - In the package and module summary pages, I replaced the `&nbsp;`  in the heading with an ordinary space character as the full content of the `<h1>` element now also appears in its `title` attribute, where entities are not supported.
 - I added an extra set of source files to test Use pages in `TestUnnamedPackage` as the existing sources contained an illegal Java file, causing `PackageUseWriter` to fail.

-------------

Commit messages:
 - JDK-8260223: Handling of unnamed package in javadoc pages

Changes: https://git.openjdk.java.net/jdk/pull/2648/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=2648&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8260223
  Stats: 208 lines in 33 files changed: 103 ins; 38 del; 67 mod
  Patch: https://git.openjdk.java.net/jdk/pull/2648.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/2648/head:pull/2648

PR: https://git.openjdk.java.net/jdk/pull/2648

[Jonathan Gibbons-2]

On Fri, 19 Feb 2021 15:58:48 GMT, Hannes Wallnöfer <[hidden email]> wrote:

> This replaces the unlocalized `<Unnamed>` string with a localized string resource in API docs covering code in the unnamed package. The name used in the default locale is "Unnamed Package". The old `<Unnamed>` token is still used as an internal placeholder, for example in `Extern.java` and in the search index files.
>
> Previously, we had two distinct `getPackageName(PackageElement)` methods, one in `HtmlDocletWriter` returning a Content object and one in `Utils` returning a String. The former is now changed to return the localized content resource. To disambiguate it from the latter, it is renamed to `getLocalizedPackageName`. I also added reciprocal references to the doc comments in both methods.
>
> A few minor notes on changes that may not be obvious:
>
>  - In the package and module summary pages, I replaced the `&nbsp;`  in the heading with an ordinary space character as the full content of the `<h1>` element now also appears in its `title` attribute, where entities are not supported.
>  - I added an extra set of source files to test Use pages in `TestUnnamedPackage` as the existing sources contained an illegal Java file, causing `PackageUseWriter` to fail.

Well, that was more pervasive than expected!

Nice work.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java line 53:

> 51: import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
> 52: import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
> 53: import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;

Yay, always glad to see use of `RawHtml` reduced!

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java line 187:

> 185:         Content moduleHead = new ContentBuilder();
> 186:         moduleHead.add(mdle.isOpen() && (configuration.docEnv.getModuleMode() == ModuleMode.ALL)
> 187:                 ? contents.openModuleLabel : contents.moduleLabel);

Nothing wrong here, but this is a good place to comment on the difference between "labels" (which should be localized) and keywords (which should not). I think we're getting to a better place where keywords only appear in signature block, and maybe other limited places.

-------------

Marked as reviewed by jjg (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/2648

[Hannes Wallnöfer]

On Fri, 19 Feb 2021 15:58:48 GMT, Hannes Wallnöfer <[hidden email]> wrote:

> This replaces the unlocalized `<Unnamed>` string with a localized string resource in API docs covering code in the unnamed package. The name used in the default locale is "Unnamed Package". The old `<Unnamed>` token is still used as an internal placeholder, for example in `Extern.java` and in the search index files.
>
> Previously, we had two distinct `getPackageName(PackageElement)` methods, one in `HtmlDocletWriter` returning a Content object and one in `Utils` returning a String. The former is now changed to return the localized content resource. To disambiguate it from the latter, it is renamed to `getLocalizedPackageName`. I also added reciprocal references to the doc comments in both methods.
>
> A few minor notes on changes that may not be obvious:
>
>  - In the package and module summary pages, I replaced the `&nbsp;`  in the heading with an ordinary space character as the full content of the `<h1>` element now also appears in its `title` attribute, where entities are not supported.
>  - I added an extra set of source files to test Use pages in `TestUnnamedPackage` as the existing sources contained an illegal Java file, causing `PackageUseWriter` to fail.

This pull request has now been integrated.

Changeset: a5c4b9a6
Author:    Hannes Wallnöfer <[hidden email]>
URL:       https://git.openjdk.java.net/jdk/commit/a5c4b9a6
Stats:     208 lines in 33 files changed: 103 ins; 38 del; 67 mod

8260223: Handling of unnamed package in javadoc pages

Reviewed-by: jjg

-------------

PR: https://git.openjdk.java.net/jdk/pull/2648