Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files
8258002: Update "type" terminology in generated docs
Reviewed-by: hannesw
  • Loading branch information
jonathan-gibbons committed Dec 18, 2020
1 parent 45bd3b9 commit c04c7e1f1049630ab9ee0eaa71c4779cb45c44ab
Showing 45 changed files with 511 additions and 240 deletions.
@@ -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;
}
@@ -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();
@@ -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) {
@@ -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;
@@ -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)
@@ -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);
@@ -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 @@ public class Contents {
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");
}

/**
@@ -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)
@@ -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
@@ -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 {

@@ -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);

1 comment on commit c04c7e1

@openjdk-notifier
Copy link

@openjdk-notifier openjdk-notifier bot commented on c04c7e1 Dec 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.