8241895: use new "details-list" CSS class instead of general "block-list" for list of details sections

Reviewed-by: hannesw
This commit is contained in:
Jonathan Gibbons 2020-04-07 12:41:49 -07:00
parent 8523e37f7e
commit 7ac64b81ee
18 changed files with 185 additions and 107 deletions

View File

@ -153,16 +153,13 @@ public class ConstructorWriterImpl extends AbstractExecutableMemberWriter
@Override
public Content getConstructorDetails(Content constructorDetailsTreeHeader, Content constructorDetailsTree) {
Content constructorDetails = new ContentBuilder(constructorDetailsTreeHeader, constructorDetailsTree);
return getMemberTree(HtmlTree.SECTION(HtmlStyle.constructorDetails, constructorDetails)
.setId(SectionName.CONSTRUCTOR_DETAIL.getName()));
return writer.getDetailsListItem(
HtmlTree.SECTION(HtmlStyle.constructorDetails)
.setId(SectionName.CONSTRUCTOR_DETAIL.getName())
.add(constructorDetailsTreeHeader)
.add(constructorDetailsTree));
}
/**
* Let the writer know whether a non public constructor was found.
*
* @param foundNonPubConstructor true if we found a non public constructor.
*/
@Override
public void setFoundNonPubConstructor(boolean foundNonPubConstructor) {
this.foundNonPubConstructor = foundNonPubConstructor;

View File

@ -121,10 +121,11 @@ public class EnumConstantWriterImpl extends AbstractMemberWriter
@Override
public Content getEnumConstantsDetails(Content enumConstantsDetailsTreeHeader,
Content enumConstantsDetailsTree) {
Content enumConstantsDetails =
new ContentBuilder(enumConstantsDetailsTreeHeader, enumConstantsDetailsTree);
return getMemberTree(HtmlTree.SECTION(HtmlStyle.constantDetails, enumConstantsDetails)
.setId(SectionName.ENUM_CONSTANT_DETAIL.getName()));
return writer.getDetailsListItem(
HtmlTree.SECTION(HtmlStyle.constantDetails)
.setId(SectionName.ENUM_CONSTANT_DETAIL.getName())
.add(enumConstantsDetailsTreeHeader)
.add(enumConstantsDetailsTree));
}
@Override

View File

@ -122,9 +122,11 @@ public class FieldWriterImpl extends AbstractMemberWriter
@Override
public Content getFieldDetails(Content fieldDetailsTreeHeader, Content fieldDetailsTree) {
Content fieldDetails = new ContentBuilder(fieldDetailsTreeHeader, fieldDetailsTree);
return getMemberTree(HtmlTree.SECTION(HtmlStyle.fieldDetails, fieldDetails)
.setId(SectionName.FIELD_DETAIL.getName()));
return writer.getDetailsListItem(
HtmlTree.SECTION(HtmlStyle.fieldDetails)
.setId(SectionName.FIELD_DETAIL.getName())
.add(fieldDetailsTreeHeader)
.add(fieldDetailsTree));
}
@Override

View File

@ -134,9 +134,11 @@ public class PropertyWriterImpl extends AbstractMemberWriter
@Override
public Content getPropertyDetails(Content propertyDetailsTreeHeader, Content propertyDetailsTree) {
Content propertyDetails = new ContentBuilder(propertyDetailsTreeHeader, propertyDetailsTree);
return getMemberTree(HtmlTree.SECTION(HtmlStyle.propertyDetails, propertyDetails)
.setId(SectionName.PROPERTY_DETAIL.getName()));
return writer.getDetailsListItem(
HtmlTree.SECTION(HtmlStyle.propertyDetails)
.setId(SectionName.PROPERTY_DETAIL.getName())
.add(propertyDetailsTreeHeader)
.add(propertyDetailsTree));
}
@Override

View File

@ -212,6 +212,25 @@ public abstract class SubWriterHolderWriter extends HtmlDocletWriter {
return ul;
}
/**
* Returns a list to be used for the list of details for members of a given kind.
*
* @return a list to be used for the list of details for members of a given kind
*/
public Content getDetailsList() {
return new HtmlTree(TagName.UL).setStyle(HtmlStyle.detailsList);
}
/**
* Returns an item for the list of details for members of a given kind.
*
* @param content content for the item
* @return an item for the list of details for members of a given kind
*/
public Content getDetailsListItem(Content content) {
return HtmlTree.LI(content);
}
/**
* Returns a list to be used for the list of members of a given kind.
*
@ -224,11 +243,11 @@ public abstract class SubWriterHolderWriter extends HtmlDocletWriter {
/**
* Returns an item for the list of elements of a given kind
*
* @param contentTree the tree used to generate the complete member tree
* @param content content for the item
* @return an item for the list of elements of a given kind
*/
public Content getMemberListItem(Content contentTree) {
return HtmlTree.LI(contentTree);
public Content getMemberListItem(Content content) {
return HtmlTree.LI(content);
}
public Content getMemberInheritedTree() {

View File

@ -97,29 +97,29 @@ public class WriterFactoryImpl implements WriterFactory {
@Override
public EnumConstantWriterImpl getEnumConstantWriter(ClassWriter classWriter) {
return new EnumConstantWriterImpl((SubWriterHolderWriter) classWriter,
return new EnumConstantWriterImpl((ClassWriterImpl) classWriter,
classWriter.getTypeElement());
}
@Override
public FieldWriterImpl getFieldWriter(ClassWriter classWriter) {
return new FieldWriterImpl((SubWriterHolderWriter) classWriter, classWriter.getTypeElement());
return new FieldWriterImpl((ClassWriterImpl) classWriter, classWriter.getTypeElement());
}
@Override
public PropertyWriterImpl getPropertyWriter(ClassWriter classWriter) {
return new PropertyWriterImpl((SubWriterHolderWriter) classWriter,
return new PropertyWriterImpl((ClassWriterImpl) classWriter,
classWriter.getTypeElement());
}
@Override
public MethodWriterImpl getMethodWriter(ClassWriter classWriter) {
return new MethodWriterImpl((SubWriterHolderWriter) classWriter, classWriter.getTypeElement());
return new MethodWriterImpl((ClassWriterImpl) classWriter, classWriter.getTypeElement());
}
@Override
public ConstructorWriterImpl getConstructorWriter(ClassWriter classWriter) {
return new ConstructorWriterImpl((SubWriterHolderWriter) classWriter,
return new ConstructorWriterImpl((ClassWriterImpl) classWriter,
classWriter.getTypeElement());
}

View File

@ -68,6 +68,7 @@ public enum HtmlStyle {
deprecationComment,
descfrmTypeLabel,
details,
detailsList,
detail,
externalLink,
fieldDetails,

View File

@ -171,6 +171,21 @@ public interface ClassWriter {
*/
Content getMemberTreeHeader();
/**
* Returns a list to be used for the list of details for members of a given kind.
*
* @return a list to be used for the list of details for members of a given kind
*/
Content getDetailsList();
/**
* Returns an item for the list of details for members of a given kind.
*
* @param content content for the item
* @return an item for the list of details for members of a given kind
*/
Content getDetailsListItem(Content content);
/**
* Add the class content tree.
*

View File

@ -78,7 +78,7 @@ public class AnnotationTypeRequiredMemberBuilder extends AbstractMemberBuilder {
AnnotationTypeRequiredMemberWriter writer,
VisibleMemberTable.Kind memberType) {
super(context, typeElement);
this.writer = writer;
this.writer = Objects.requireNonNull(writer);
this.members = getVisibleMembers(memberType);
}
@ -126,16 +126,13 @@ public class AnnotationTypeRequiredMemberBuilder extends AbstractMemberBuilder {
/**
* Build the member documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if an error occurs
*/
protected void buildAnnotationTypeMember(Content memberDetailsTree)
protected void buildAnnotationTypeMember(Content detailsList)
throws DocletException {
if (writer == null) {
return;
}
if (hasMembersToDocument()) {
writer.addAnnotationDetailsMarker(memberDetailsTree);
writer.addAnnotationDetailsMarker(detailsList);
Content annotationDetailsTreeHeader = writer.getAnnotationDetailsTreeHeader();
Content memberList = writer.getMemberList();
@ -147,7 +144,8 @@ public class AnnotationTypeRequiredMemberBuilder extends AbstractMemberBuilder {
memberList.add(writer.getMemberListItem(annotationDocTree));
}
memberDetailsTree.add(writer.getAnnotationDetails(annotationDetailsTreeHeader, memberList));
Content annotationDetails = writer.getAnnotationDetails(annotationDetailsTreeHeader, memberList);
detailsList.add(annotationDetails);
}
}

View File

@ -335,67 +335,67 @@ public class ClassBuilder extends AbstractBuilder {
* @throws DocletException if there is a problem while building the documentation
*/
protected void buildMemberDetails(Content classContentTree) throws DocletException {
Content memberDetailsTree = writer.getMemberTreeHeader();
Content detailsList = writer.getDetailsList();
buildEnumConstantsDetails(memberDetailsTree);
buildPropertyDetails(memberDetailsTree);
buildFieldDetails(memberDetailsTree);
buildConstructorDetails(memberDetailsTree);
buildAnnotationTypeRequiredMemberDetails(memberDetailsTree);
buildAnnotationTypeOptionalMemberDetails(memberDetailsTree);
buildMethodDetails(memberDetailsTree);
buildEnumConstantsDetails(detailsList);
buildPropertyDetails(detailsList);
buildFieldDetails(detailsList);
buildConstructorDetails(detailsList);
buildAnnotationTypeRequiredMemberDetails(detailsList);
buildAnnotationTypeOptionalMemberDetails(detailsList);
buildMethodDetails(detailsList);
classContentTree.add(writer.getMemberDetailsTree(memberDetailsTree));
classContentTree.add(writer.getMemberDetailsTree(detailsList));
}
/**
* Build the enum constants documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if there is a problem while building the documentation
*/
protected void buildEnumConstantsDetails(Content memberDetailsTree) throws DocletException {
builderFactory.getEnumConstantsBuilder(writer).build(memberDetailsTree);
protected void buildEnumConstantsDetails(Content detailsList) throws DocletException {
builderFactory.getEnumConstantsBuilder(writer).build(detailsList);
}
/**
* Build the field documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if there is a problem while building the documentation
*/
protected void buildFieldDetails(Content memberDetailsTree) throws DocletException {
builderFactory.getFieldBuilder(writer).build(memberDetailsTree);
protected void buildFieldDetails(Content detailsList) throws DocletException {
builderFactory.getFieldBuilder(writer).build(detailsList);
}
/**
* Build the property documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if there is a problem while building the documentation
*/
public void buildPropertyDetails( Content memberDetailsTree) throws DocletException {
builderFactory.getPropertyBuilder(writer).build(memberDetailsTree);
public void buildPropertyDetails( Content detailsList) throws DocletException {
builderFactory.getPropertyBuilder(writer).build(detailsList);
}
/**
* Build the constructor documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if there is a problem while building the documentation
*/
protected void buildConstructorDetails(Content memberDetailsTree) throws DocletException {
builderFactory.getConstructorBuilder(writer).build(memberDetailsTree);
protected void buildConstructorDetails(Content detailsList) throws DocletException {
builderFactory.getConstructorBuilder(writer).build(detailsList);
}
/**
* Build the method documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if there is a problem while building the documentation
*/
protected void buildMethodDetails(Content memberDetailsTree) throws DocletException {
builderFactory.getMethodBuilder(writer).build(memberDetailsTree);
protected void buildMethodDetails(Content detailsList) throws DocletException {
builderFactory.getMethodBuilder(writer).build(detailsList);
}
/**

View File

@ -74,7 +74,7 @@ public class ConstructorBuilder extends AbstractMemberBuilder {
TypeElement typeElement,
ConstructorWriter writer) {
super(context, typeElement);
this.writer = writer;
this.writer = Objects.requireNonNull(writer);
constructors = getVisibleMembers(CONSTRUCTORS);
for (Element ctor : constructors) {
if (utils.isProtected(ctor) || utils.isPrivate(ctor)) {
@ -118,15 +118,12 @@ public class ConstructorBuilder extends AbstractMemberBuilder {
/**
* Build the constructor documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if there is a problem while building the documentation
*/
protected void buildConstructorDoc(Content memberDetailsTree) throws DocletException {
if (writer == null) {
return;
}
protected void buildConstructorDoc(Content detailsList) throws DocletException {
if (hasMembersToDocument()) {
Content constructorDetailsTreeHeader = writer.getConstructorDetailsTreeHeader(memberDetailsTree);
Content constructorDetailsTreeHeader = writer.getConstructorDetailsTreeHeader(detailsList);
Content memberList = writer.getMemberList();
for (Element constructor : constructors) {
@ -140,8 +137,8 @@ public class ConstructorBuilder extends AbstractMemberBuilder {
memberList.add(writer.getMemberListItem(constructorDocTree));
}
memberDetailsTree.add(
writer.getConstructorDetails(constructorDetailsTreeHeader, memberList));
Content constructorDetails = writer.getConstructorDetails(constructorDetailsTreeHeader, memberList);
detailsList.add(constructorDetails);
}
}

View File

@ -74,7 +74,7 @@ public class EnumConstantBuilder extends AbstractMemberBuilder {
private EnumConstantBuilder(Context context,
TypeElement typeElement, EnumConstantWriter writer) {
super(context, typeElement);
this.writer = writer;
this.writer = Objects.requireNonNull(writer);
enumConstants = getVisibleMembers(ENUM_CONSTANTS);
}
@ -109,16 +109,13 @@ public class EnumConstantBuilder extends AbstractMemberBuilder {
/**
* Build the enum constant documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException is there is a problem while building the documentation
*/
protected void buildEnumConstant(Content memberDetailsTree) throws DocletException {
if (writer == null) {
return;
}
protected void buildEnumConstant(Content detailsList) throws DocletException {
if (hasMembersToDocument()) {
Content enumConstantsDetailsTreeHeader = writer.getEnumConstantsDetailsTreeHeader(typeElement,
memberDetailsTree);
detailsList);
Content memberList = writer.getMemberList();
for (Element enumConstant : enumConstants) {
@ -133,8 +130,9 @@ public class EnumConstantBuilder extends AbstractMemberBuilder {
memberList.add(writer.getMemberListItem(enumConstantsTree));
}
memberDetailsTree.add(
writer.getEnumConstantsDetails(enumConstantsDetailsTreeHeader, memberList));
Content enumConstantDetails = writer.getEnumConstantsDetails(
enumConstantsDetailsTreeHeader, memberList);
detailsList.add(enumConstantDetails);
}
}

View File

@ -75,7 +75,7 @@ public class FieldBuilder extends AbstractMemberBuilder {
TypeElement typeElement,
FieldWriter writer) {
super(context, typeElement);
this.writer = writer;
this.writer = Objects.requireNonNull(writer);
fields = getVisibleMembers(FIELDS);
}
@ -111,15 +111,12 @@ public class FieldBuilder extends AbstractMemberBuilder {
/**
* Build the field documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if there is a problem while building the documentation
*/
protected void buildFieldDoc(Content memberDetailsTree) throws DocletException {
if (writer == null) {
return;
}
protected void buildFieldDoc(Content detailsList) throws DocletException {
if (!fields.isEmpty()) {
Content fieldDetailsTreeHeader = writer.getFieldDetailsTreeHeader(memberDetailsTree);
Content fieldDetailsTreeHeader = writer.getFieldDetailsTreeHeader(detailsList);
Content memberList = writer.getMemberList();
for (Element element : fields) {
@ -133,8 +130,8 @@ public class FieldBuilder extends AbstractMemberBuilder {
memberList.add(writer.getMemberListItem(fieldDocTree));
}
memberDetailsTree.add(
writer.getFieldDetails(fieldDetailsTreeHeader, memberList));
Content fieldDetails = writer.getFieldDetails(fieldDetailsTreeHeader, memberList);
detailsList.add(fieldDetails);
}
}

View File

@ -78,7 +78,7 @@ public class MethodBuilder extends AbstractMemberBuilder {
TypeElement typeElement,
MethodWriter writer) {
super(context, typeElement);
this.writer = writer;
this.writer = Objects.requireNonNull(writer);
methods = getVisibleMembers(METHODS);
}
@ -109,15 +109,12 @@ public class MethodBuilder extends AbstractMemberBuilder {
/**
* Build the method documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if there is a problem while building the documentation
*/
protected void buildMethodDoc(Content memberDetailsTree) throws DocletException {
if (writer == null) {
return;
}
protected void buildMethodDoc(Content detailsList) throws DocletException {
if (hasMembersToDocument()) {
Content methodDetailsTreeHeader = writer.getMethodDetailsTreeHeader(memberDetailsTree);
Content methodDetailsTreeHeader = writer.getMethodDetailsTreeHeader(detailsList);
Content memberList = writer.getMemberList();
for (Element method : methods) {
@ -131,7 +128,8 @@ public class MethodBuilder extends AbstractMemberBuilder {
memberList.add(writer.getMemberListItem(methodDocTree));
}
memberDetailsTree.add(writer.getMethodDetails(methodDetailsTreeHeader, memberList));
Content methodDetails = writer.getMethodDetails(methodDetailsTreeHeader, memberList);
detailsList.add(methodDetails);
}
}

View File

@ -75,7 +75,7 @@ public class PropertyBuilder extends AbstractMemberBuilder {
TypeElement typeElement,
PropertyWriter writer) {
super(context, typeElement);
this.writer = writer;
this.writer = Objects.requireNonNull(writer);
properties = getVisibleMembers(PROPERTIES);
}
@ -111,15 +111,12 @@ public class PropertyBuilder extends AbstractMemberBuilder {
/**
* Build the property documentation.
*
* @param memberDetailsTree the content tree to which the documentation will be added
* @param detailsList the content tree to which the documentation will be added
* @throws DocletException if there is a problem while building the documentation
*/
protected void buildPropertyDoc(Content memberDetailsTree) throws DocletException {
if (writer == null) {
return;
}
protected void buildPropertyDoc(Content detailsList) throws DocletException {
if (hasMembersToDocument()) {
Content propertyDetailsTreeHeader = writer.getPropertyDetailsTreeHeader(memberDetailsTree);
Content propertyDetailsTreeHeader = writer.getPropertyDetailsTreeHeader(detailsList);
Content memberList = writer.getMemberList();
for (Element property : properties) {
@ -132,8 +129,8 @@ public class PropertyBuilder extends AbstractMemberBuilder {
memberList.add(writer.getMemberListItem(propertyDocTree));
}
memberDetailsTree.add(
writer.getPropertyDetails(propertyDetailsTreeHeader, memberList));
Content propertyDetails = writer.getPropertyDetails(propertyDetailsTreeHeader, memberList);
detailsList.add(propertyDetails);
}
}

View File

@ -321,11 +321,11 @@ div.inheritance {
div.inheritance div.inheritance {
margin-left:2em;
}
ul.block-list, ul.member-list {
ul.block-list, ul.details-list, ul.member-list {
margin:10px 0 10px 0;
padding:0;
}
ul.block-list > li, ul.member-list > li {
ul.block-list > li, ul.details-list > li, ul.member-list > li {
list-style:none;
margin-bottom:15px;
line-height:1.4;

View File

@ -394,7 +394,7 @@ public class TestHtmlVersion extends JavadocTester {
+ "<h2>Optional Element Summary</h2>\n"
+ "<div class=\"member-summary\">\n<table>",
"<section class=\"details\" id=\"annotation.type.element.detail\">\n"
+ "<ul class=\"block-list\">\n"
+ "<ul class=\"details-list\">\n"
+ "<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->\n"
+ "<li>\n"
+ "<section class=\"member-details\">\n"

View File

@ -23,8 +23,8 @@
/*
* @test
* @bug 8241625
* @summary test the lists genereated by the doclet
* @bug 8241625 8241895
* @summary test the lists generated by the doclet
* @library /tools/lib ../../lib
* @modules jdk.javadoc/jdk.javadoc.internal.tool
* @build toolbox.ToolBox javadoc.tester.*
@ -97,4 +97,60 @@ public class TestLists extends JavadocTester {
+ "<li>\n"
+ "<section class=\"detail\" id=\"value()\">");
}
@Test
public void testDetailLists(Path base) throws IOException {
Path src = base.resolve("src");
tb.writeJavaFiles(src,
"package p; public class C {\n"
+ " public C() { }\n"
+ " public C(int i) { }\n"
+ " public int f1;\n"
+ " public int f2;\n"
+ " public void m1() { }\n"
+ " public void m2() { }\n"
+ "}\n",
"package p; public enum E { E1, E2 }\n",
"package p; public @interface A { int value(); }\n"
);
javadoc("-d", base.resolve("out").toString(),
"-sourcepath", src.toString(),
"p");
checkExit(Exit.OK);
checkOutput("p/C.html", true,
"<section class=\"details\">\n"
+ "<ul class=\"details-list\">\n"
+ "<!-- ============ FIELD DETAIL =========== -->\n"
+ "<li>\n"
+ "<section class=\"field-details\" id=\"field.detail\">\n"
+ "<h2>Field Details</h2>\n"
+ "<ul class=\"member-list\">",
"</ul>\n"
+ "</section>\n"
+ "</li>\n"
+ "<!-- ========= CONSTRUCTOR DETAIL ======== -->\n"
+ "<li>\n"
+ "<section class=\"constructor-details\" id=\"constructor.detail\">\n"
+ "<h2>Constructor Details</h2>\n"
+ "<ul class=\"member-list\">");
checkOutput("p/E.html", true,
"<section class=\"details\">\n"
+ "<ul class=\"details-list\">\n"
+ "<!-- ============ ENUM CONSTANT DETAIL =========== -->\n"
+ "<li>\n"
+ "<section class=\"constant-details\" id=\"enum.constant.detail\">\n"
+ "<h2>Enum Constant Details</h2>\n"
+ "<ul class=\"member-list\">");
checkOutput("p/A.html", true,
"<ul class=\"details-list\">\n"
+ "<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->\n"
+ "<li>\n"
+ "<section class=\"member-details\">\n"
+ "<h2>Element Details</h2>\n"
+ "<ul class=\"member-list\">");
}
}