archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 07:14:30 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8239804: Cleanup/simplify HTML/CSS for general block tags

Browse source 
Reviewed-by: prappo, hannesw
This commit is contained in:
Jonathan Gibbons 2020-02-27 12:16:03 -08:00
parent 4a951001b5
commit 39d75e894b
55 changed files with 349 additions and 349 deletions
Download patch file Download diff file Expand all files Collapse all files

2
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java
View file

@ -351,7 +351,7 @@ public class ClassWriterImpl extends SubWriterHolderWriter implements ClassWrite
Content paramInfo = (new ParamTaglet()).getTagletOutput(typeElement,
getTagletWriterInstance(false));
if (!paramInfo.isEmpty()) {
classInfoTree.add(HtmlTree.DL(paramInfo));
classInfoTree.add(HtmlTree.DL(paramInfo).setStyle(HtmlStyle.notes));
}
}
}

14
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java
View file

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

8
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
View file

@ -342,13 +342,13 @@ public class HtmlDocletWriter {
* 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 @@ public class HtmlDocletWriter {
configuration.tagletManager.getBlockTaglets(e),
getTagletWriterInstance(false), output);
dl.add(output);
htmltree.add(dl);
htmlTree.add(dl);
}
/**

2
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlSerialFieldWriter.java
View file

@ -200,7 +200,7 @@ public class HtmlSerialFieldWriter extends FieldWriterImpl
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?
}

2
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlSerialMethodWriter.java
View file

@ -159,7 +159,7 @@ public class HtmlSerialMethodWriter extends MethodWriterImpl implements
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

46
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/MethodWriterImpl.java
View file

@ -241,36 +241,48 @@ public class MethodWriterImpl extends AbstractExecutableMemberWriter
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 @@ public class MethodWriterImpl extends AbstractExecutableMemberWriter
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 @@ public class MethodWriterImpl extends AbstractExecutableMemberWriter
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);

4
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java
View file

@ -184,9 +184,7 @@ public class SerializedFormWriterImpl extends SubWriterHolderWriter
*/
@Override
public Content getSerialUIDInfoHeader() {
HtmlTree dl = new HtmlTree(HtmlTag.DL);
dl.setStyle(HtmlStyle.nameValue);
return dl;
return new HtmlTree(HtmlTag.DL).setStyle(HtmlStyle.nameValue);
}
/**

53
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java
View file

@ -51,6 +51,7 @@ import jdk.javadoc.internal.doclets.toolkit.Content;
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 class TagletWriterImpl extends TagletWriter {
options = configuration.getOptions();
utils = configuration.utils;
resources = configuration.getDocResources();
contents = configuration.getContents();
}
@Override
@ -174,10 +177,15 @@ public class TagletWriterImpl extends TagletWriter {
}
@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 class TagletWriterImpl extends TagletWriter {
@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 class TagletWriterImpl extends TagletWriter {
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 @@ public class TagletWriterImpl extends TagletWriter {
@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 class TagletWriterImpl extends TagletWriter {
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 @@ public class TagletWriterImpl extends TagletWriter {
@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

8
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2010, 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
@ -103,7 +103,7 @@ public enum HtmlStyle {
navListSearch,
navPadding,
nestedClassSummary,
overrideSpecifyLabel,
notes,
overviewSummary,
packages,
packageDescription,
@ -111,22 +111,18 @@ public enum HtmlStyle {
packageLabelInType,
packagesSummary,
packageUses,
paramLabel,
propertyDetails,
propertySummary,
providesSummary,
requiresSummary,
returnLabel,
returnType,
rowColor,
searchTagLink,
searchTagResult,
seeLabel,
serializedFormContainer,
serializedPackageContainer,
serializedClassDetails,
servicesSummary,
simpleTagLabel,
skipNav,
sourceContainer,
sourceLineNo,

3
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties
View file

@ -1,5 +1,5 @@
#
# Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2010, 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
@ -103,7 +103,6 @@ doclet.RecordComponents_dup_warn=Record component "{0}" is documented more than
doclet.Returns=Returns:
doclet.Return_tag_on_void_method=@return tag cannot be used in method with void return type.
doclet.See_Also=See Also:
doclet.See=See:
doclet.SerialData=Serial Data:
doclet.Services=Services
doclet.Since=Since:

6
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
View file

@ -562,10 +562,12 @@ h1.hidden {
margin:0 10px 5px 0;
color:#474747;
}
dl.notes > dt {
font-weight:bold;
}
.deprecatedLabel, .descfrmTypeLabel, .implementationLabel, .memberNameLabel, .memberNameLink,
.moduleLabelInPackage, .moduleLabelInType, .overrideSpecifyLabel, .packageLabelInType,
.packageHierarchyLabel, .paramLabel, .returnLabel, .seeLabel, .simpleTagLabel,
.throwsLabel, .typeNameLabel, .typeNameLink, .searchTagLink {
.packageHierarchyLabel, .typeNameLabel, .typeNameLink, .searchTagLink {
font-weight:bold;
}
.deprecationComment, .emphasizedPhrase, .interfaceName {

14
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java
View file

@ -42,7 +42,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
/**
* A taglet that represents the @param tag.
* A taglet that represents the {@code @param} tag.
*
* <p><b>This is NOT part of any supported API.
* If you write code that depends on this, you do so at your own risk.
@ -50,7 +50,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.Utils;
* deletion without notice.</b>
*/
public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
private enum ParamKind {
public enum ParamKind {
/** Parameter of an executable element. */
PARAMETER,
/** State components of a record. */
@ -298,15 +298,7 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
boolean isFirstParam) {
Content result = writer.getOutputInstance();
if (isFirstParam) {
String key;
switch (kind) {
case PARAMETER: key = "doclet.Parameters" ; break;
case TYPE_PARAMETER: key = "doclet.TypeParameters" ; break;
case RECORD_COMPONENT: key = "doclet.RecordComponents" ; break;
default: throw new IllegalArgumentException(kind.toString());
}
String header = writer.configuration().getDocResources().getText(key);
result.add(writer.getParamHeader(header));
result.add(writer.getParamHeader(kind));
}
result.add(writer.paramTagOutput(e, paramTag, name));
return result;

6
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletWriter.java
View file

@ -107,10 +107,10 @@ public abstract class TagletWriter {
/**
* Return the header for the param tags.
*
* @param header the header to display.
* @return the header for the param tags.
* @param kind the kind of header that is required
* @return the header for the param tags
*/
protected abstract Content getParamHeader(String header);
protected abstract Content getParamHeader(ParamTaglet.ParamKind kind);
/**
* Return the output for param tags.