Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files
8239804: Cleanup/simplify HTML/CSS for general block tags
Reviewed-by: prappo, hannesw
  • Loading branch information
jonathan-gibbons committed Feb 27, 2020
1 parent 4a95100 commit 39d75e894b6cafcf701cf946132ed7a056b071db
Showing with 349 additions and 349 deletions.
  1. +2 −4 make/jdk/src/classes/build/tools/taglet/ModuleGraph.java
  2. +2 −2 make/jdk/src/classes/build/tools/taglet/ToolGuide.java
  3. +1 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java
  4. +12 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java
  5. +4 −4 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
  6. +1 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlSerialFieldWriter.java
  7. +1 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlSerialMethodWriter.java
  8. +33 −13 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/MethodWriterImpl.java
  9. +1 −3 ...jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java
  10. +26 −27 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java
  11. +2 −6 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java
  12. +1 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties
  13. +4 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
  14. +3 −11 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java
  15. +3 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletWriter.java
  16. +5 −4 test/langtools/jdk/javadoc/doclet/AuthorDD/AuthorDD.java
  17. +4 −4 test/langtools/jdk/javadoc/doclet/testAuthor/TestAuthor.java
  18. +2 −2 test/langtools/jdk/javadoc/doclet/testClassCrossReferences/TestClassCrossReferences.java
  19. +4 −4 test/langtools/jdk/javadoc/doclet/testConstructorIndent/TestConstructorIndent.java
  20. +2 −2 test/langtools/jdk/javadoc/doclet/testConstructors/TestConstructors.java
  21. +3 −3 test/langtools/jdk/javadoc/doclet/testCopyFiles/TestCopyFiles.java
  22. +7 −7 ...estExternalOverridenMethod/{TestExternalOverridenMethod.java → TestExternalOverriddenMethod.java}
  23. +3 −3 test/langtools/jdk/javadoc/doclet/testHiddenMembers/TestHiddenMembers.java
  24. +1 −1 test/langtools/jdk/javadoc/doclet/testHref/TestHref.java
  25. +56 −72 test/langtools/jdk/javadoc/doclet/testHtmlDefinitionListTag/TestHtmlDefinitionListTag.java
  26. +2 −2 test/langtools/jdk/javadoc/doclet/testHtmlStrongTag/TestHtmlStrongTag.java
  27. +2 −2 test/langtools/jdk/javadoc/doclet/testHtmlTag/TestHtmlTag.java
  28. +5 −5 test/langtools/jdk/javadoc/doclet/testInterface/TestInterface.java
  29. +23 −23 test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFX.java
  30. +4 −4 test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java
  31. +2 −2 test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java
  32. +8 −8 test/langtools/jdk/javadoc/doclet/testModules/TestModules.java
  33. +9 −9 test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java
  34. +2 −2 test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestMultiInheritance.java
  35. +2 −2 test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverriddenMethodDocCopy.java
  36. +7 −7 test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverriddenPrivateMethods.java
  37. +5 −5 ...ngtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverriddenPrivateMethodsWithPackageFlag.java
  38. +13 −13 ...ngtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverriddenPrivateMethodsWithPrivateFlag.java
  39. +4 −4 test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java
  40. +6 −6 test/langtools/jdk/javadoc/doclet/testOverriddenMethods/pkg1/BaseClass.java
  41. +2 −2 test/langtools/jdk/javadoc/doclet/testOverriddenMethods/pkg1/SubClass.java
  42. +4 −4 test/langtools/jdk/javadoc/doclet/testParamTaglet/TestParamTaglet.java
  43. +6 −6 test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java
  44. +2 −2 test/langtools/jdk/javadoc/doclet/testPrivateClasses/pkg/PrivateParent.java
  45. +2 −2 test/langtools/jdk/javadoc/doclet/testPrivateClasses/pkg/PublicChild.java
  46. +7 −7 test/langtools/jdk/javadoc/doclet/testProperty/TestProperty.java
  47. +7 −7 test/langtools/jdk/javadoc/doclet/testRecordTypes/TestRecordTypes.java
  48. +6 −6 test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java
  49. +9 −9 ...tools/jdk/javadoc/doclet/testSerializedFormDeprecationInfo/TestSerializedFormDeprecationInfo.java
  50. +8 −7 test/langtools/jdk/javadoc/doclet/testSimpleTag/TestSimpleTag.java
  51. +3 −3 test/langtools/jdk/javadoc/doclet/testSimpleTagInherit/TestSimpleTagInherit.java
  52. +6 −6 test/langtools/jdk/javadoc/doclet/testSinceTag/TestSinceTag.java
  53. +3 −3 test/langtools/jdk/javadoc/doclet/testThrowsHead/TestThrowsHead.java
  54. +3 −3 test/langtools/jdk/javadoc/doclet/testValueTag/TestValueTag.java
  55. +4 −4 test/langtools/jdk/javadoc/doclet/testVersionTag/TestVersionTag.java
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -73,9 +73,7 @@ public String toString(List<? extends DocTree> tags, Element element) {
+ getImage(moduleName, imageFile, -1, true)
+ "</span>";
}
return "<dt>"
+ "<span class=\"simpleTagLabel\">Module Graph:</span>\n"
+ "</dt>"
return "<dt>Module Graph:</dt>"
+ "<dd>"
+ "<a class=moduleGraph href=\"" + imageFile + "\">"
+ getImage(moduleName, imageFile, thumbnailHeight, false)
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -95,7 +95,7 @@ public String toString(List<? extends DocTree> tags, Element elem) {
return "";

StringBuilder sb = new StringBuilder();
sb.append("<dt class=\"simpleTagLabel\">Tool Guides:</dt>\n")
sb.append("<dt>Tool Guides:</dt>\n")
.append("<dd>");

boolean needComma = false;
@@ -351,7 +351,7 @@ public void addParamInfo(Content classInfoTree) {
Content paramInfo = (new ParamTaglet()).getTagletOutput(typeElement,
getTagletWriterInstance(false));
if (!paramInfo.isEmpty()) {
classInfoTree.add(HtmlTree.DL(paramInfo));
classInfoTree.add(HtmlTree.DL(paramInfo).setStyle(HtmlStyle.notes));
}
}
}
@@ -151,13 +151,16 @@ public class Contents {
public final Content packageLabel;
public final Content package_;
public final Content packagesLabel;
public final Content parameters;
public final Content properties;
public final Content propertyLabel;
public final Content propertyDetailsLabel;
public final Content propertySummaryLabel;
public final Content record;
public final Content recordComponents;
public final Content referencedIn;
public final Content seeLabel;
public final Content returns;
public final Content seeAlso;
public final Content serializedForm;
public final Content servicesLabel;
public final Content specifiedByLabel;
@@ -166,8 +169,10 @@ public class Contents {
public final Content summaryLabel;
public final Content systemPropertiesLabel;
public final Content systemPropertiesSummaryLabel;
public final Content throws_;
public final Content treeLabel;
public final Content typeLabel;
public final Content typeParameters;
public final Content useLabel;
public final Content valueLabel;

@@ -282,13 +287,16 @@ public class Contents {
packageLabel = getContent("doclet.Package");
package_ = getContent("doclet.package");
packagesLabel = getContent("doclet.Packages");
parameters = getContent("doclet.Parameters");
properties = getContent("doclet.Properties");
propertyLabel = getContent("doclet.Property");
propertyDetailsLabel = getContent("doclet.Property_Detail");
propertySummaryLabel = getContent("doclet.Property_Summary");
record = getContent("doclet.Record");
recordComponents = getContent("doclet.RecordComponents");
referencedIn = getContent("doclet.ReferencedIn");
seeLabel = getContent("doclet.See");
returns = getContent("doclet.Returns");
seeAlso = getContent("doclet.See_Also");
serializedForm = getContent("doclet.Serialized_Form");
servicesLabel = getContent("doclet.Services");
specifiedByLabel = getContent("doclet.Specified_By");
@@ -297,8 +305,10 @@ public class Contents {
summaryLabel = getContent("doclet.Summary");
systemPropertiesLabel = getContent("doclet.systemProperties");
systemPropertiesSummaryLabel = getContent("doclet.systemPropertiesSummary");
throws_ = getContent("doclet.Throws");
treeLabel = getContent("doclet.Tree");
typeLabel = getContent("doclet.Type");
typeParameters = getContent("doclet.TypeParameters");
useLabel = getContent("doclet.navClassUse");
valueLabel = getContent("doclet.Value");

@@ -342,13 +342,13 @@ private void addMethodInfo(ExecutableElement method, Content dl) {
* Adds the tags information.
*
* @param e the Element for which the tags will be generated
* @param htmltree the documentation tree to which the tags will be added
* @param htmlTree the documentation tree to which the tags will be added
*/
protected void addTagsInfo(Element e, Content htmltree) {
protected void addTagsInfo(Element e, Content htmlTree) {
if (options.noComment()) {
return;
}
Content dl = new HtmlTree(HtmlTag.DL);
Content dl = new HtmlTree(HtmlTag.DL).setStyle(HtmlStyle.notes);
if (utils.isExecutableElement(e) && !utils.isConstructor(e)) {
addMethodInfo((ExecutableElement)e, dl);
}
@@ -357,7 +357,7 @@ protected void addTagsInfo(Element e, Content htmltree) {
configuration.tagletManager.getBlockTaglets(e),
getTagletWriterInstance(false), output);
dl.add(output);
htmltree.add(dl);
htmlTree.add(dl);
}

/**
@@ -200,7 +200,7 @@ public void addMemberTags(VariableElement field, Content contentTree) {
TagletWriter.genTagOutput(configuration.tagletManager, field,
configuration.tagletManager.getBlockTaglets(field),
writer.getTagletWriterInstance(false), tagContent);
Content dlTags = new HtmlTree(HtmlTag.DL);
Content dlTags = new HtmlTree(HtmlTag.DL).setStyle(HtmlStyle.notes);
dlTags.add(tagContent);
contentTree.add(dlTags); // TODO: what if empty?
}
@@ -159,7 +159,7 @@ public void addMemberTags(ExecutableElement member, Content methodsContentTree)
TagletWriter.genTagOutput(tagletManager, member,
tagletManager.getSerializedFormTaglets(),
writer.getTagletWriterInstance(false), tagContent);
Content dlTags = new HtmlTree(HtmlTag.DL);
Content dlTags = new HtmlTree(HtmlTag.DL).setStyle(HtmlStyle.notes);
dlTags.add(tagContent);
methodsContentTree.add(dlTags);
if (name(member).compareTo("writeExternal") == 0
@@ -241,36 +241,48 @@ protected void addSummaryType(Element member, Content tdSummaryType) {
addModifierAndType(meth, utils.getReturnType(typeElement, meth), tdSummaryType);
}

/**
* Adds "overrides" or "specified by" information about a method (if appropriate)
* into a definition list.
*
* @param writer the writer for the element
* @param overriddenType the superclass
* @param method the method
* @param dl the list in which to add the information.
*/
protected static void addOverridden(HtmlDocletWriter writer,
TypeMirror overriddenType, ExecutableElement method, Content dl) {
TypeMirror overriddenType,
ExecutableElement method,
Content dl) {
if (writer.options.noComment()) {
return;
}
Utils utils = writer.utils;
Contents contents = writer.contents;
TypeElement holder = utils.getEnclosingTypeElement(method);
if (!(utils.isPublic(holder) ||
utils.isLinkable(holder))) {
if (!(utils.isPublic(holder) || utils.isLinkable(holder))) {
//This is an implementation detail that should not be documented.
return;
}
if (utils.isIncluded(holder) && ! utils.isIncluded(method)) {
if (utils.isIncluded(holder) && !utils.isIncluded(method)) {
//The class is included but the method is not. That means that it
//is not visible so don't document this.
return;
}
Content label = contents.overridesLabel;
LinkInfoImpl.Kind context = LinkInfoImpl.Kind.METHOD_OVERRIDES;

if (method != null) {
Contents contents = writer.contents;
Content label;
LinkInfoImpl.Kind context;
if (utils.isAbstract(holder) && utils.isAbstract(method)){
//Abstract method is implemented from abstract class,
//not overridden
label = contents.specifiedByLabel;
context = LinkInfoImpl.Kind.METHOD_SPECIFIED_BY;
} else {
label = contents.overridesLabel;
context = LinkInfoImpl.Kind.METHOD_OVERRIDES;
}
Content dt = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.overrideSpecifyLabel, label));
dl.add(dt);
dl.add(HtmlTree.DT(label));
Content overriddenTypeLink =
writer.getLink(new LinkInfoImpl(writer.configuration, context, overriddenType));
Content codeOverriddenTypeLink = HtmlTree.CODE(overriddenTypeLink);
@@ -281,15 +293,24 @@ protected static void addOverridden(HtmlDocletWriter writer,
Content codeMethLink = HtmlTree.CODE(methlink);
Content dd = HtmlTree.DD(codeMethLink);
dd.add(Entity.NO_BREAK_SPACE);
dd.add(writer.contents.inClass);
dd.add(contents.inClass);
dd.add(Entity.NO_BREAK_SPACE);
dd.add(codeOverriddenTypeLink);
dl.add(dd);
}
}

/**
* Adds "implements" information for a method (if appropriate)
* into a definition list.
*
* @param writer the writer for the method
* @param method the method
* @param dl the definition list
*/
protected static void addImplementsInfo(HtmlDocletWriter writer,
ExecutableElement method, Content dl) {
ExecutableElement method,
Content dl) {
Utils utils = writer.utils;
if (utils.isStatic(method) || writer.options.noComment()) {
return;
@@ -306,8 +327,7 @@ protected static void addImplementsInfo(HtmlDocletWriter writer,
Content intfaclink = writer.getLink(new LinkInfoImpl(
writer.configuration, LinkInfoImpl.Kind.METHOD_SPECIFIED_BY, intfac));
Content codeIntfacLink = HtmlTree.CODE(intfaclink);
Content dt = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.overrideSpecifyLabel, contents.specifiedByLabel));
dl.add(dt);
dl.add(HtmlTree.DT(contents.specifiedByLabel));
Content methlink = writer.getDocLink(
LinkInfoImpl.Kind.MEMBER, implementedMeth,
implementedMeth.getSimpleName(), false);
@@ -184,9 +184,7 @@ public Content getClassHeader(TypeElement typeElement) {
*/
@Override
public Content getSerialUIDInfoHeader() {
HtmlTree dl = new HtmlTree(HtmlTag.DL);
dl.setStyle(HtmlStyle.nameValue);
return dl;
return new HtmlTree(HtmlTag.DL).setStyle(HtmlStyle.nameValue);
}

/**
@@ -51,6 +51,7 @@
import jdk.javadoc.internal.doclets.toolkit.DocletElement;
import jdk.javadoc.internal.doclets.toolkit.Resources;
import jdk.javadoc.internal.doclets.toolkit.builders.SerializedFormBuilder;
import jdk.javadoc.internal.doclets.toolkit.taglets.ParamTaglet;
import jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
@@ -76,6 +77,7 @@ public class TagletWriterImpl extends TagletWriter {
private final Utils utils;
private final boolean inSummary;
private final Resources resources;
private final Contents contents;

public TagletWriterImpl(HtmlDocletWriter htmlWriter, boolean isFirstSentence) {
this(htmlWriter, isFirstSentence, false);
@@ -89,6 +91,7 @@ public TagletWriterImpl(HtmlDocletWriter htmlWriter, boolean isFirstSentence, bo
options = configuration.getOptions();
utils = configuration.utils;
resources = configuration.getDocResources();
contents = configuration.getContents();
}

@Override
@@ -174,10 +177,15 @@ protected Content literalTagOutput(Element element, DocTree tag) {
}

@Override
public Content getParamHeader(String header) {
HtmlTree result = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.paramLabel,
new StringContent(header)));
return result;
public Content getParamHeader(ParamTaglet.ParamKind kind) {
Content header;
switch (kind) {
case PARAMETER: header = contents.parameters ; break;
case TYPE_PARAMETER: header = contents.typeParameters ; break;
case RECORD_COMPONENT: header = contents.recordComponents ; break;
default: throw new IllegalArgumentException(kind.toString());
}
return HtmlTree.DT(header);
}

@Override
@@ -210,13 +218,11 @@ public Content propertyTagOutput(Element element, DocTree tag, String prefix) {

@Override
public Content returnTagOutput(Element element, DocTree returnTag) {
ContentBuilder result = new ContentBuilder();
CommentHelper ch = utils.getCommentHelper(element);
result.add(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.returnLabel,
new StringContent(resources.getText("doclet.Returns")))));
result.add(HtmlTree.DD(htmlWriter.commentTagsToContent(
returnTag, element, ch.getDescription(returnTag), false, inSummary)));
return result;
return new ContentBuilder(
HtmlTree.DT(contents.returns),
HtmlTree.DD(htmlWriter.commentTagsToContent(
returnTag, element, ch.getDescription(returnTag), false, inSummary)));
}

@Override
@@ -253,12 +259,9 @@ public Content seeTagOutput(Element holder, List<? extends DocTree> seeTags) {
if (body.isEmpty())
return body;

ContentBuilder result = new ContentBuilder();
result.add(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.seeLabel,
new StringContent(resources.getText("doclet.See_Also")))));
result.add(HtmlTree.DD(body));
return result;

return new ContentBuilder(
HtmlTree.DT(contents.seeAlso),
HtmlTree.DD(body));
}

private void appendSeparatorIfNotEmpty(ContentBuilder body) {
@@ -271,8 +274,6 @@ private void appendSeparatorIfNotEmpty(ContentBuilder body) {
@Override
public Content simpleTagOutput(Element element, List<? extends DocTree> simpleTags, String header) {
CommentHelper ch = utils.getCommentHelper(element);
ContentBuilder result = new ContentBuilder();
result.add(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.simpleTagLabel, new RawHtml(header))));
ContentBuilder body = new ContentBuilder();
boolean many = false;
for (DocTree simpleTag : simpleTags) {
@@ -283,19 +284,19 @@ public Content simpleTagOutput(Element element, List<? extends DocTree> simpleTa
body.add(htmlWriter.commentTagsToContent(simpleTag, element, bodyTags, false, inSummary));
many = true;
}
result.add(HtmlTree.DD(body));
return result;
return new ContentBuilder(
HtmlTree.DT(new RawHtml(header)),
HtmlTree.DD(body));
}

@Override
public Content simpleTagOutput(Element element, DocTree simpleTag, String header) {
ContentBuilder result = new ContentBuilder();
result.add(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.simpleTagLabel, new RawHtml(header))));
CommentHelper ch = utils.getCommentHelper(element);
List<? extends DocTree> description = ch.getDescription(simpleTag);
Content body = htmlWriter.commentTagsToContent(simpleTag, element, description, false, inSummary);
result.add(HtmlTree.DD(body));
return result;
return new ContentBuilder(
HtmlTree.DT(new RawHtml(header)),
HtmlTree.DD(body));
}

@Override
@@ -308,9 +309,7 @@ protected Content systemPropertyTagOutput(Element element, DocTree tag) {

@Override
public Content getThrowsHeader() {
HtmlTree result = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.throwsLabel,
new StringContent(resources.getText("doclet.Throws"))));
return result;
return HtmlTree.DT(contents.throws_);
}

@Override

0 comments on commit 39d75e8

Please sign in to comment.