[jdk16] RFR: JDK-8258002: Update "type" terminology in generated docs [v2]

[Hannes Wallnöfer]

On Thu, 17 Dec 2020 19:58:10 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This is the work to update javadoc to use certain terminology dependent on the source version in use.
>> 
>> The groups of terms being changed are:
>> 
>> * `Types` to `Classes and Interfaces`
>> * `Annotation Type` to `Annotation Interface`
>> * `Enum` to `Enum Class`
>> 
>> The new terminology will be used when the source version of the elements being documented is 16 or higher. This is the default behavior. The corollary is that the old terminology will be used when the `--source` or `--release` option is used to specify a version less than `16`.
>> 
>> In addition, the terminology for `Record` is being unconditionally changed to use `Record Class`. Since the feature was in preview before this release, there is no need to be able to generate the previous form.
>> 
>> Also, in the course of this work, it was noted that on the "Use" page for an annotation type/interface, it was incorrectly classified as a *class*, instead of *annotation interface*: that has been fixed.
>> 
>> Fundamentally, the change is managed at a very low level, by passing a _mapping function_ into `Resource.getText`. This allows high level code, `HtmlDoclet` in this case, to provide version-specific overrides of the resource key to be used. The avoids having to have version-specific checks at the point of use for each affected resource.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains seven commits:
> 
>  - Fix failures
>  - Merge with upstream/master
>  - remove adaptive terminology for records
>  - add test
>  - Remove obsolete properties and code
>  - Version 2: release-specific terminology
>  - JDK-8258002: Update "type" terminology in generated docs

Looks good, Jon.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeOptionalMemberWriterImpl.java line 28:

> 26: package jdk.javadoc.internal.doclets.formats.html;
> 27: 
> 28: import javax.lang.model.SourceVersion;

Unused import

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java line 186:

> 184: 
> 185:         messages = new Messages(this, msgResources);
> 186:         //contents = new Contents(this);

Should be removed instead of commented out

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java line 204:

> 202:         super.initConfiguration(docEnv, resourceKeyMapper);
> 203:         contents = new Contents(this);
> 204:     }

I wish initialization of the configuration instance was not that complex... I guess the reason we must do it this way is that used SourceVersion is not known earlier.

test/langtools/jdk/javadoc/doclet/testTerminology/TestTerminology.java line 153:

> 151: //                        var catTypes = "Classes and Interfaces";"""
> 152: //        );
> 153: // awaits JDK-8247994: localize JavaScript search

Should be working now :)

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk16/pull/20