8258002: Update "type" terminology in generated docs

Reviewed-by: hannesw
openjdk · Dec 18, 2020 · c04c7e1 · c04c7e1 · openjdk-notifier · Dec 18, 2020
1 parent 45bd3b9
commit c04c7e1
Show file tree

Hide file tree

Showing 45 changed files with 511 additions and 240 deletions.
diff --git a/...javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java b/...javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java
@@ -27,13 +27,9 @@
 
 import java.util.ArrayList;
 import java.util.List;
-import java.util.Set;
-import java.util.TreeSet;
-import java.util.stream.Collectors;
 
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
-import javax.lang.model.element.Modifier;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.element.TypeParameterElement;
 import javax.lang.model.type.TypeMirror;
@@ -46,23 +42,15 @@
 import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
 import jdk.javadoc.internal.doclets.formats.html.markup.Links;
-import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
 import jdk.javadoc.internal.doclets.formats.html.markup.Table;
 import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader;
 import jdk.javadoc.internal.doclets.toolkit.Content;
 import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter;
 import jdk.javadoc.internal.doclets.toolkit.MemberWriter;
 import jdk.javadoc.internal.doclets.toolkit.Resources;
 import jdk.javadoc.internal.doclets.toolkit.taglets.DeprecatedTaglet;
-import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
 
-import static javax.lang.model.element.Modifier.ABSTRACT;
-import static javax.lang.model.element.Modifier.NATIVE;
-import static javax.lang.model.element.Modifier.PUBLIC;
-import static javax.lang.model.element.Modifier.STRICTFP;
-import static javax.lang.model.element.Modifier.SYNCHRONIZED;
-
 /**
  * The base class for member writers.
  *
@@ -89,7 +77,7 @@ public AbstractMemberWriter(SubWriterHolderWriter writer, TypeElement typeElemen
         this.writer = writer;
         this.typeElement = typeElement;
         this.utils = configuration.utils;
-        this.contents = configuration.contents;
+        this.contents = configuration.getContents();
         this.resources = configuration.docResources;
         this.links = writer.links;
     }

diff --git a/...avadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesIndexWriter.java b/...avadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesIndexWriter.java
@@ -116,12 +116,12 @@ protected void addContents(Content content) {
                 .setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colLast)
                 .setId("all-classes-table")
                 .setDefaultTab(resources.getText("doclet.All_Classes"))
-                .addTab(resources.interfaceSummary, utils::isInterface)
-                .addTab(resources.classSummary, e -> utils.isOrdinaryClass((TypeElement)e))
-                .addTab(resources.enumSummary, utils::isEnum)
-                .addTab(resources.exceptionSummary, e -> utils.isException((TypeElement)e))
-                .addTab(resources.errorSummary, e -> utils.isError((TypeElement)e))
-                .addTab(resources.annotationTypeSummary, utils::isAnnotationType);
+                .addTab(contents.interfaceSummary, utils::isInterface)
+                .addTab(contents.classSummary, e -> utils.isOrdinaryClass((TypeElement)e))
+                .addTab(contents.enumSummary, utils::isEnum)
+                .addTab(contents.exceptionSummary, e -> utils.isException((TypeElement)e))
+                .addTab(contents.errorSummary, e -> utils.isError((TypeElement)e))
+                .addTab(contents.annotationTypeSummary, utils::isAnnotationType);
         for (Character unicode : indexBuilder.getFirstCharacters()) {
             for (IndexItem indexItem : indexBuilder.getItems(unicode)) {
                 TypeElement typeElement = (TypeElement) indexItem.getElement();

diff --git a/...vadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllPackagesIndexWriter.java b/...vadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllPackagesIndexWriter.java
@@ -96,7 +96,7 @@ protected void buildAllPackagesFile() throws DocFileIOException {
      */
     protected void addPackages(Content content) {
         Table table = new Table(HtmlStyle.summaryTable)
-                .setCaption(new StringContent(resources.packageSummary))
+                .setCaption(new StringContent(contents.packageSummary))
                 .setHeader(new TableHeader(contents.packageLabel, contents.descriptionLabel))
                 .setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colLast);
         for (PackageElement pkg : configuration.packages) {

diff --git a/...ses/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeOptionalMemberWriterImpl.java b/...ses/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeOptionalMemberWriterImpl.java
@@ -66,8 +66,9 @@ public AnnotationTypeOptionalMemberWriterImpl(SubWriterHolderWriter writer,
     @Override
     public Content getMemberSummaryHeader(TypeElement typeElement,
             Content memberSummaryTree) {
-        memberSummaryTree.add(
-                MarkerComments.START_OF_ANNOTATION_TYPE_OPTIONAL_MEMBER_SUMMARY);
+        memberSummaryTree.add(selectComment(
+                MarkerComments.START_OF_ANNOTATION_TYPE_OPTIONAL_MEMBER_SUMMARY,
+                MarkerComments.START_OF_ANNOTATION_INTERFACE_OPTIONAL_MEMBER_SUMMARY));
         Content memberTree = new ContentBuilder();
         writer.addSummaryHeader(this, memberTree);
         return memberTree;

diff --git a/...ses/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeRequiredMemberWriterImpl.java b/...ses/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeRequiredMemberWriterImpl.java
@@ -25,11 +25,13 @@
 
 package jdk.javadoc.internal.doclets.formats.html;
 
+import javax.lang.model.SourceVersion;
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.type.TypeMirror;
 
+import jdk.javadoc.internal.doclets.formats.html.markup.Comment;
 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
@@ -66,8 +68,9 @@ public AnnotationTypeRequiredMemberWriterImpl(SubWriterHolderWriter writer,
     @Override
     public Content getMemberSummaryHeader(TypeElement typeElement,
             Content memberSummaryTree) {
-        memberSummaryTree.add(
-                MarkerComments.START_OF_ANNOTATION_TYPE_REQUIRED_MEMBER_SUMMARY);
+        memberSummaryTree.add(selectComment(
+                MarkerComments.START_OF_ANNOTATION_TYPE_REQUIRED_MEMBER_SUMMARY,
+                MarkerComments.START_OF_ANNOTATION_INTERFACE_REQUIRED_MEMBER_SUMMARY));
         Content memberTree = new ContentBuilder();
         writer.addSummaryHeader(this, memberTree);
         return memberTree;
@@ -86,7 +89,9 @@ public void addSummary(Content summariesList, Content content) {
 
     @Override
     public void addAnnotationDetailsMarker(Content memberDetails) {
-        memberDetails.add(MarkerComments.START_OF_ANNOTATION_TYPE_DETAILS);
+        memberDetails.add(selectComment(
+                MarkerComments.START_OF_ANNOTATION_TYPE_DETAILS,
+                MarkerComments.START_OF_ANNOTATION_INTERFACE_DETAILS));
     }
 
     @Override
@@ -201,6 +206,12 @@ protected Content getDeprecatedLink(Element member) {
         return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name);
     }
 
+    protected Comment selectComment(Comment c1, Comment c2) {
+        HtmlConfiguration configuration = writer.configuration;
+        SourceVersion sv = configuration.docEnv.getSourceVersion();
+        return sv.compareTo(SourceVersion.RELEASE_16) < 0 ? c1 : c2;
+    }
+
     private TypeMirror getType(Element member) {
         return utils.isExecutableElement(member)
                 ? utils.getReturnType(typeElement, (ExecutableElement) member)

diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java
@@ -412,9 +412,13 @@ protected void addClassUse(PackageElement pkg, Content contentTree) {
      * @return a content tree representing the class use header
      */
     protected HtmlTree getClassUseHeader() {
-        String cltype = resources.getText(utils.isInterface(typeElement)
-                ? "doclet.Interface"
-                : "doclet.Class");
+        String cltype = resources.getText(switch (typeElement.getKind()) {
+            case ANNOTATION_TYPE -> "doclet.AnnotationType";
+            case INTERFACE -> "doclet.Interface";
+            case RECORD -> "doclet.RecordClass";
+            case ENUM -> "doclet.Enum";
+            default -> "doclet.Class";
+        });
         String clname = utils.getFullyQualifiedName(typeElement);
         String title = resources.getText("doclet.Window_ClassUse_Header",
                 cltype, clname);

diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java
@@ -177,6 +177,15 @@ public class Contents {
 
     private final EnumMap<VisibleMemberTable.Kind, Content> navLinkLabels;
 
+    public final String annotationTypeSummary;
+    public final String classSummary;
+    public final String enumSummary;
+    public final String errorSummary;
+    public final String exceptionSummary;
+    public final String interfaceSummary;
+    public final String packageSummary;
+    public final String recordSummary;
+
     private final Resources resources;
 
     /**
@@ -289,7 +298,7 @@ public class Contents {
         propertyLabel = getContent("doclet.Property");
         propertyDetailsLabel = getContent("doclet.Property_Detail");
         propertySummaryLabel = getContent("doclet.Property_Summary");
-        record = getContent("doclet.Record");
+        record = getContent("doclet.RecordClass");
         recordComponents = getContent("doclet.RecordComponents");
         referencedIn = getContent("doclet.ReferencedIn");
         returns = getContent("doclet.Returns");
@@ -315,6 +324,15 @@ record = getContent("doclet.Record");
         navLinkLabels.put(VisibleMemberTable.Kind.FIELDS, getContent("doclet.navField"));
         navLinkLabels.put(VisibleMemberTable.Kind.CONSTRUCTORS, getContent("doclet.navConstructor"));
         navLinkLabels.put(VisibleMemberTable.Kind.METHODS, getContent("doclet.navMethod"));
+
+        this.annotationTypeSummary = resources.getText("doclet.Annotation_Types_Summary");
+        this.classSummary = resources.getText("doclet.Class_Summary");
+        this.enumSummary = resources.getText("doclet.Enum_Summary");
+        this.errorSummary = resources.getText("doclet.Error_Summary");
+        this.exceptionSummary = resources.getText("doclet.Exception_Summary");
+        this.interfaceSummary = resources.getText("doclet.Interface_Summary");
+        this.packageSummary = resources.getText("doclet.Package_Summary");
+        this.recordSummary = resources.getText("doclet.Record_Class_Summary");
     }
 
     /**

diff --git a/...javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java b/...javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java
@@ -78,13 +78,13 @@ private String getAnchorName(DeprElementKind kind) {
             case CLASS:
                 return "class";
             case ENUM:
-                return "enum";
+                return "enum.class";
             case EXCEPTION:
                 return "exception";
             case ERROR:
                 return "error";
             case ANNOTATION_TYPE:
-                return "annotation.type";
+                return "annotation.interface";
             case FIELD:
                 return "field";
             case METHOD:
@@ -94,7 +94,7 @@ private String getAnchorName(DeprElementKind kind) {
             case ENUM_CONSTANT:
                 return "enum.constant";
             case ANNOTATION_TYPE_MEMBER:
-                return "annotation.type.member";
+                return "annotation.interface.member";
             case RECORD_CLASS:
                 return "record.class";
             default:
@@ -197,7 +197,7 @@ private String getHeaderKey(DeprElementKind kind) {
             case ANNOTATION_TYPE:
                 return "doclet.AnnotationType";
             case RECORD_CLASS:
-                return "doclet.Record";
+                return "doclet.RecordClass";
             case FIELD:
                 return "doclet.Field";
             case METHOD:
@@ -287,17 +287,13 @@ protected void generateDeprecatedListFile(DeprecatedAPIListBuilder deprAPI)
             throws DocFileIOException {
         HtmlTree body = getHeader();
         bodyContents.addMainContent(getContentsList(deprAPI));
-        String memberTableSummary;
         Content content = new ContentBuilder();
         for (DeprElementKind kind : DeprElementKind.values()) {
             if (deprAPI.hasDocumentation(kind)) {
-                memberTableSummary = resources.getText("doclet.Member_Table_Summary",
-                        resources.getText(getHeadingKey(kind)),
-                        resources.getText(getSummaryKey(kind)));
                 TableHeader memberTableHeader = new TableHeader(
                         contents.getContent(getHeaderKey(kind)), contents.descriptionLabel);
                 addDeprecatedAPI(deprAPI.getSet(kind), getAnchorName(kind),
-                            getHeadingKey(kind), memberTableSummary, memberTableHeader, content);
+                            getHeadingKey(kind), memberTableHeader, content);
             }
         }
         bodyContents.addMainContent(content);
@@ -368,12 +364,11 @@ public HtmlTree getHeader() {
      * @param deprList list of deprecated API elements
      * @param id the id attribute of the table
      * @param headingKey the caption for the deprecated table
-     * @param tableSummary the summary for the deprecated table
      * @param tableHeader table headers for the deprecated table
      * @param contentTree the content tree to which the deprecated table will be added
      */
     protected void addDeprecatedAPI(SortedSet<Element> deprList, String id, String headingKey,
-            String tableSummary, TableHeader tableHeader, Content contentTree) {
+            TableHeader tableHeader, Content contentTree) {
         if (deprList.size() > 0) {
             Content caption = contents.getContent(headingKey);
             Table table = new Table(HtmlStyle.summaryTable)

diff --git a/...dk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java b/...dk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java
@@ -32,7 +32,9 @@
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Set;
+import java.util.function.Function;
 import java.util.stream.Collectors;
 import javax.lang.model.element.Element;
 import javax.lang.model.element.PackageElement;
@@ -118,7 +120,7 @@ public class HtmlConfiguration extends BaseConfiguration {
      */
     protected DeprecatedAPIListBuilder deprecatedAPIListBuilder;
 
-    public final Contents contents;
+    private Contents contents;
 
     protected final Messages messages;
 
@@ -181,7 +183,6 @@ public HtmlConfiguration(Doclet doclet, Locale locale, Reporter reporter) {
         }
 
         messages = new Messages(this, msgResources);
-        contents = new Contents(this);
         options = new HtmlOptions(this);
 
         Runtime.Version v;
@@ -195,6 +196,11 @@ public HtmlConfiguration(Doclet doclet, Locale locale, Reporter reporter) {
 
         conditionalPages = EnumSet.noneOf(ConditionalPage.class);
     }
+    protected void initConfiguration(DocletEnvironment docEnv,
+                                     Function<String, String> resourceKeyMapper) {
+        super.initConfiguration(docEnv, resourceKeyMapper);
+        contents = new Contents(this);
+    }
 
     private final Runtime.Version docletVersion;
     public final Date startTime = new Date();
@@ -215,7 +221,7 @@ public Resources getDocResources() {
      * @return a utility object providing commonly used fragments of content
      */
     public Contents getContents() {
-        return contents;
+        return Objects.requireNonNull(contents);
     }
 
     @Override

diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
@@ -26,12 +26,15 @@
 package jdk.javadoc.internal.doclets.formats.html;
 
 import java.util.*;
+import java.util.function.Function;
 
+import javax.lang.model.SourceVersion;
 import javax.lang.model.element.ModuleElement;
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 
 import jdk.javadoc.doclet.Doclet;
+import jdk.javadoc.doclet.DocletEnvironment;
 import jdk.javadoc.doclet.Reporter;
 import jdk.javadoc.internal.doclets.toolkit.AbstractDoclet;
 import jdk.javadoc.internal.doclets.toolkit.DocletException;
@@ -115,6 +118,52 @@ public HtmlConfiguration getConfiguration() {
         return configuration;
     }
 
+    @Override
+    protected Function<String, String> getResourceKeyMapper(DocletEnvironment docEnv) {
+        SourceVersion sv = docEnv.getSourceVersion();
+        Map<String, String> map = new HashMap<>();
+        String[][] pairs = {
+                // in standard.properties
+                { "doclet.Enum_Hierarchy", "doclet.Enum_Class_Hierarchy" },
+                { "doclet.Annotation_Type_Hierarchy", "doclet.Annotation_Interface_Hierarchy" },
+                { "doclet.Href_Enum_Title", "doclet.Href_Enum_Class_Title" },
+                { "doclet.Annotation_Types", "doclet.Annotation_Interfaces" },
+                { "doclet.Annotation_Type_Members", "doclet.Annotation_Interface_Members" },
+                { "doclet.annotation_types", "doclet.annotation_interfaces" },
+                { "doclet.annotation_type_members", "doclet.annotation_interface_members" },
+                { "doclet.help.enum.intro", "doclet.help.enum.class.intro" },
+                { "doclet.help.annotation_type.intro", "doclet.help.annotation_interface.intro" },
+                { "doclet.help.annotation_type.declaration", "doclet.help.annotation_interface.declaration" },
+                { "doclet.help.annotation_type.description", "doclet.help.annotation_interface.description" },
+
+                // in doclets.properties
+                { "doclet.Annotation_Types_Summary", "doclet.Annotation_Interfaces_Summary" },
+                { "doclet.Enum_Summary", "doclet.Enum_Class_Summary" },
+                { "doclet.Enums", "doclet.EnumClasses" },
+                { "doclet.AnnotationType", "doclet.AnnotationInterface" },
+                { "doclet.AnnotationTypes", "doclet.AnnotationInterfaces" },
+                { "doclet.annotationtype", "doclet.annotationinterface" },
+                { "doclet.annotationtypes", "doclet.annotationinterfaces" },
+                { "doclet.Enum", "doclet.EnumClass" },
+                { "doclet.enum", "doclet.enumclass" },
+                { "doclet.enums", "doclet.enumclasses" },
+                { "doclet.Annotation_Type_Member", "doclet.Annotation_Interface_Member" },
+                { "doclet.enum_values_doc.fullbody", "doclet.enum_class_values_doc.fullbody" },
+                { "doclet.enum_values_doc.return", "doclet.enum_class_values_doc.return" },
+                { "doclet.enum_valueof_doc.fullbody", "doclet.enum_class_valueof_doc.fullbody" },
+                { "doclet.enum_valueof_doc.throws_ila", "doclet.enum_class_valueof_doc.throws_ila" },
+                { "doclet.search.types", "doclet.search.classes_and_interfaces"}
+        };
+        for (String[] pair : pairs) {
+            if (sv.compareTo(SourceVersion.RELEASE_16) >= 0) {
+                map.put(pair[0], pair[1]);
+            } else {
+                map.put(pair[1], pair[0]);
+            }
+        }
+        return (k) -> map.getOrDefault(k, k);
+    }
+
     @Override // defined by AbstractDoclet
     public void generateClassFiles(ClassTree classTree) throws DocletException {
 

diff --git a/...jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java b/...jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
@@ -216,7 +216,7 @@ public class HtmlDocletWriter {
     public HtmlDocletWriter(HtmlConfiguration configuration, DocPath path) {
         this.configuration = configuration;
         this.options = configuration.getOptions();
-        this.contents = configuration.contents;
+        this.contents = configuration.getContents();
         this.messages = configuration.messages;
         this.resources = configuration.docResources;
         this.links = new Links(path, configuration.utils);