Skip to content
Permalink
Browse files

8241470: HtmlStyle: group and document members: description, flex, si…

…gnature

Reviewed-by: hannesw
  • Loading branch information
jonathan-gibbons committed Mar 27, 2020
1 parent 5f1636b commit 87805d92078144d2c61bc901239ea5cd6844d66f
@@ -686,7 +686,7 @@ private void appendParametersAndExceptions(Content htmltree, int lastLineSeparat
parameters.add(")");
htmltree.add(Entity.ZERO_WIDTH_SPACE);
htmltree.add("(");
htmltree.add(HtmlTree.SPAN(HtmlStyle.arguments, parameters));
htmltree.add(HtmlTree.SPAN(HtmlStyle.parameters, parameters));
}

// Exceptions
@@ -48,8 +48,6 @@
aboutLanguage,
activeTableTab,
altColor,
annotations,
arguments,
block,
blockList,
bottomNav,
@@ -68,18 +66,13 @@
deprecatedSummary,
deprecationBlock,
deprecationComment,
description,
descfrmTypeLabel,
details,
detail,
emphasizedPhrase,
exceptions,
externalLink,
fieldDetails,
fieldSummary,
flexBox,
flexHeader,
flexContent,
header,
helpSection,
hierarchy,
@@ -91,28 +84,21 @@
interfaceName,
legalCopy,
memberDetails,
memberName,
memberNameLabel,
memberNameLink,
memberSignature,
memberSummary,
methodDetails,
methodSummary,
modifiers,
moduleDescription,
moduleLabelInPackage,
moduleLabelInType,
moduleTags,
modulesSummary,
nameValue,
navBarCell1Rev,
navList,
navListSearch,
nestedClassSummary,
notes,
overviewSummary,
packages,
packageDescription,
packageHierarchyLabel,
packageLabelInType,
packagesSummary,
@@ -121,7 +107,6 @@
propertySummary,
providesSummary,
requiresSummary,
returnType,
rowColor,
searchTagLink,
searchTagResult,
@@ -142,13 +127,133 @@
topNav,
typeNameLabel,
typeNameLink,
typeParameters,
typeParametersLong,
typeSummary,
useSummary,
usesSummary,
verticalSeparator,
//<editor-fold desc="documentation comments">
// The following constants are used for the components used to present the content
// generated from documentation comments.
/**
* The class of the element used to present the documentation comment for a type or member
* element.
* The content of the block tags will be in a nested element with class {@link #notes}.
*/
description,
/**
* The class of the element used to present the documentation comment for a module element,
* excluding block tags.
* The content of the block tags will be in a sibling element with class {@link #moduleTags}.
*/
moduleDescription,
/**
* The class of the {@code dl} element used to present the block tags in the documentation
* comment for a module element.
* Additional (derived) information, such as implementation or inheritance details, may
* also appear in this element.
*/
moduleTags,
/**
* The class of the element used to present the documentation comment for package element.
* The content of the block tags will be in a nested element with class {@link #notes}.
*/
packageDescription,
/**
* The class of the {@code dl} element used to present the block tags in the documentation
* comment for a package, type or member element.
* Additional (derived) information, such as implementation or inheritance details, may
* also appear in this element.
*/
notes,
//</editor-fold>
//<editor-fold desc="flex layout">
// The following constants are used for the components of the top-level structures for "flex" layout.
/**
* The class of the top-level {@code div} element used to arrange for "flex" layout in
* a browser window. The element should contain two child elements: one with class
* {@link #flexHeader flex-header} and one with class {@link #flexContent flex-content}.
*/
flexBox,
/**
* The class of the {@code header} element within a {@link #flexBox flex-box} container.
* The element is always displayed at the top of the viewport.
*/
flexHeader,
/**
* The class of the {@code div} element within a {@link #flexBox flex-box} container
* This element appears below the header and can be scrolled if too big for the available height.
*/
flexContent,
//</editor-fold>
//<editor-fold desc="member signature">
// The following constants are used for the components of a signature of an element
/**
* The class of a {@code span} element for the signature of an element.
* The signature will contain a member name and, depending on the kind of element,
* it can contain any of the following:
* annotations, type parameters, modifiers, return type, parameters, and exceptions.
*/
memberSignature,
/**
* The class of a {@code span} element for any annotations in the signature of an element.
*/
annotations,
/**
* The class of a {@code span} element for any exceptions in a signature of an executable element.
*/
exceptions,
/**
* The class of a {@code span} for the member name in the signature of an element.
*/
memberName,
/**
* The class of a {@code span} for any modifiers in the signature of an element.
*/
modifiers,
/**
* The class of a {@code span} for any parameters in the signature of an executable element.
*/
parameters,
/**
* The class of a {@code span} for the return type in the signature of an method element.
*/
returnType,
/**
* The class of a {@code span} for type parameters in the signature of an element,
* used when the type parameters should reasonably be displayed inline.
*/
typeParameters,
/**
* The class of a {@code span} for type parameters in the signature of an element,
* used when the type parameters are too long to be displayed inline.
* @implNote
* The threshold for choosing between {@code typeParameters} and {@code typeParametersLong}
* is 50 characters.
*/
typeParametersLong,
//</editor-fold>
//<editor-fold desc="page styles for <body> elements">
// The following constants are used for the class of the {@code <body>} element
// for the corresponding pages.
@@ -256,6 +361,7 @@
* The class of the {@code body} element for the page for the class hierarchy.
*/
treePage;
//</editor-fold>

private final String cssName;

@@ -531,7 +531,7 @@ div.member-signature span.annotations {
white-space: pre-wrap;
}
div.member-signature span.type-parameters-long,
div.member-signature span.arguments,
div.member-signature span.parameters,
div.member-signature span.exceptions {
display: inline-block;
vertical-align: top;
@@ -51,7 +51,7 @@ public void test() {
"<div class=\"member-signature\"><span class=\"modifiers\">public</span>&nbsp;"
+ "<span class=\"type-parameters\">&lt;T&gt;</span>&nbsp;"
+ "<span class=\"return-type\">void</span>&nbsp;<span class=\"member-name\">m</span>"
+ "&#8203;(<span class=\"arguments\">T&nbsp;t1,\n"
+ "&#8203;(<span class=\"parameters\">T&nbsp;t1,\n"
+ "T&nbsp;t2)</span>\n"
+ " throws <span class=\"exceptions\">java.lang.Exception</span></div>");

@@ -58,7 +58,7 @@ public void test1() {
+ "<a href=\"#setRate(double)\"><code>setRate(double)</code></a></dd>",
"<div class=\"member-signature\"><span class=\"modifiers\">public final</span>&nbsp;"
+ "<span class=\"return-type\">void</span>&nbsp;<span class=\"member-name\">setRate</span>&#8203;"
+ "(<span class=\"arguments\">double&nbsp;value)</span></div>\n"
+ "(<span class=\"parameters\">double&nbsp;value)</span></div>\n"
+ "<div class=\"block\">Sets the value of the property rate.</div>\n"
+ "<dl class=\"notes\">\n"
+ "<dt>Property description:</dt>",
@@ -103,7 +103,7 @@ public void test1() {
+ "<h3>setPaused</h3>\n"
+ "<div class=\"member-signature\"><span class=\"modifiers\">public final</span>&nbsp;"
+ "<span class=\"return-type\">void</span>&nbsp;<span class=\"member-name\">setPaused</span>&#8203;"
+ "(<span class=\"arguments\">boolean&nbsp;value)</span></div>\n"
+ "(<span class=\"parameters\">boolean&nbsp;value)</span></div>\n"
+ "<div class=\"block\">Sets the value of the property paused.</div>\n"
+ "<dl class=\"notes\">\n"
+ "<dt>Property description:</dt>\n"
@@ -132,7 +132,7 @@ public void test1() {
+ "<h3>setRate</h3>\n"
+ "<div class=\"member-signature\"><span class=\"modifiers\">public final</span>&nbsp;"
+ "<span class=\"return-type\">void</span>&nbsp;<span class=\"member-name\">setRate</span>&#8203;"
+ "(<span class=\"arguments\">double&nbsp;value)</span></div>\n"
+ "(<span class=\"parameters\">double&nbsp;value)</span></div>\n"
+ "<div class=\"block\">Sets the value of the property rate.</div>\n"
+ "<dl class=\"notes\">\n"
+ "<dt>Property description:</dt>\n"
@@ -125,7 +125,7 @@ public void test() {
+ "<div class=\"member-signature\"><span class=\"modifiers\">protected abstract</span>"
+ "&nbsp;<span class=\"return-type\">java.lang.String</span>&nbsp;"
+ "<span class=\"member-name\">parentMethod</span>&#8203;"
+ "(<span class=\"arguments\">java.lang.String&nbsp;t)</span>\n"
+ "(<span class=\"parameters\">java.lang.String&nbsp;t)</span>\n"
+ " "
+ "throws <span class=\"exceptions\">java.lang.IllegalArgumentException,\n"
+ "java.lang.InterruptedException,\n"
@@ -158,7 +158,7 @@ public void test() {
+ "<h3 id=\"method(java.lang.Object)\">method</h3>\n"
+ "<div class=\"member-signature\"><span class=\"modifiers\">public</span>"
+ "&nbsp;<span class=\"return-type\">java.lang.String</span>&nbsp;"
+ "<span class=\"member-name\">method</span>&#8203;(<span class=\"arguments\">"
+ "<span class=\"member-name\">method</span>&#8203;(<span class=\"parameters\">"
+ "java.lang.String&nbsp;t)</span></div>\n"
+ "</section>");
}
@@ -23,7 +23,7 @@

/*
* @test
* @bug 8214126
* @bug 8214126 8241470
* @summary Method signatures not formatted correctly in browser
* @library ../../lib/
* @modules jdk.javadoc/jdk.javadoc.internal.tool
@@ -55,15 +55,15 @@ public void test() {

"<div class=\"member-signature\"><span class=\"modifiers\">public static</span>"
+ "&nbsp;<span class=\"return-type\">void</span>&nbsp;<span class=\"member-name\">"
+ "simpleMethod</span>&#8203;(<span class=\"arguments\">int&nbsp;i,\n"
+ "simpleMethod</span>&#8203;(<span class=\"parameters\">int&nbsp;i,\n"
+ "java.lang.String&nbsp;s,\nboolean&nbsp;b)</span></div>",

"<div class=\"member-signature\"><span class=\"annotations\">@Generated"
+ "(value=\"SomeGeneratedName\",\n date=\"a date\",\n"
+ " comments=\"some comment about the method below\")\n"
+ "</span><span class=\"modifiers\">public static</span>&nbsp;<span "
+ "class=\"return-type\">void</span>&nbsp;<span class=\"member-name\">annotatedMethod"
+ "</span>&#8203;(<span class=\"arguments\">int&nbsp;i,\n"
+ "</span>&#8203;(<span class=\"parameters\">int&nbsp;i,\n"
+ "java.lang.String&nbsp;s,\nboolean&nbsp;b)</span></div>",

"<div class=\"member-signature\"><span class=\"modifiers\">public static</span>"
@@ -79,7 +79,7 @@ public void test() {
+ "title=\"class in pkg\">C.With8Types</a>&lt;T1,&#8203;T2,&#8203;T3,"
+ "&#8203;T4,&#8203;T5,&#8203;T6,&#8203;T7,&#8203;T8&gt;</span>&nbsp;"
+ "<span class=\"member-name\">bigGenericMethod</span>&#8203;("
+ "<span class=\"arguments\"><a href=\"C.F0.html\" "
+ "<span class=\"parameters\"><a href=\"C.F0.html\" "
+ "title=\"interface in pkg\">C.F0</a>&lt;? extends T1&gt;&nbsp;t1,\n"
+ "<a href=\"C.F0.html\" title=\"interface in pkg\">"
+ "C.F0</a>&lt;? extends T2&gt;&nbsp;t2,\n"
@@ -117,7 +117,7 @@ public void test() {
+ "title=\"class in pkg\">C.With8Types</a>&lt;T1,&#8203;T2,&#8203;T3,"
+ "&#8203;T4,&#8203;T5,&#8203;T6,&#8203;T7,&#8203;T8&gt;</span>&nbsp;"
+ "<span class=\"member-name\">bigGenericAnnotatedMethod</span>&#8203;("
+ "<span class=\"arguments\"><a href=\"C.F0.html\" "
+ "<span class=\"parameters\"><a href=\"C.F0.html\" "
+ "title=\"interface in pkg\">C.F0</a>&lt;? extends T1&gt;&nbsp;t1,\n"
+ "<a href=\"C.F0.html\" title=\"interface in pkg\">"
+ "C.F0</a>&lt;? extends T2&gt;&nbsp;t2,\n"
@@ -83,7 +83,7 @@ void checkEnums() {
"<div class=\"member-signature\"><span class=\"modifiers\">public static</span>&nbsp;"
+ "<span class=\"return-type\"><a href=\"Coin.html\" title=\"enum in pkg\">Coin</a></span>&nbsp;"
+ "<span class=\"member-name\">valueOf</span>&#8203;("
+ "<span class=\"arguments\">java.lang.String&nbsp;name)</span></div>\n" +
+ "<span class=\"parameters\">java.lang.String&nbsp;name)</span></div>\n" +
"<div class=\"block\">Returns the enum constant of this type with the specified name.\n" +
"The string must match <i>exactly</i> an identifier used to declare an\n" +
"enum constant in this type. (Extraneous whitespace characters are \n" +
@@ -135,7 +135,7 @@ void checkTypeParameters() {
"<div class=\"member-signature\"><span class=\"modifiers\">public</span>&nbsp;"
+ "<span class=\"type-parameters\">&lt;T extends java.util.List,&#8203;\nV&gt;</span>\n"
+ "<span class=\"return-type\">java.lang.String[]</span>&nbsp;<span class=\"member-name\">"
+ "methodThatHasTypeParameters</span>&#8203;(<span class=\"arguments\">T&nbsp;param1,\n"
+ "methodThatHasTypeParameters</span>&#8203;(<span class=\"parameters\">T&nbsp;param1,\n"
+ "V&nbsp;param2)</span></div>",
// Method that returns TypeParameters
"<td class=\"col-first\"><code><a href=\"TypeParameters.html\" "
@@ -147,7 +147,7 @@ void checkTypeParameters() {
"<div class=\"member-signature\"><span class=\"modifiers\">public</span>&nbsp;<span "
+ "class=\"return-type\"><a href=\"TypeParameters.html\" title=\"type parameter in TypeParameters\">"
+ "E</a>[]</span>&nbsp;<span class=\"member-name\">methodThatReturnsTypeParameterA</span>&#8203;("
+ "<span class=\"arguments\"><a href=\"TypeParameters.html\" title=\"type parameter in TypeParameters\">"
+ "<span class=\"parameters\"><a href=\"TypeParameters.html\" title=\"type parameter in TypeParameters\">"
+ "E</a>[]&nbsp;e)</span></div>\n",
"<td class=\"col-first\"><code>&lt;T extends java.lang.Object &amp; java.lang.Comparable&lt;? super T&gt;&gt;"
+ "<br>T</code></td>\n"
@@ -218,7 +218,7 @@ void checkTypeParameters() {
"<div class=\"member-signature\"><span class=\"modifiers\">public</span>&nbsp;"
+ "<span class=\"type-parameters\">&lt;T extends java.lang.Number &amp; java.lang.Runnable&gt;</span>\n"
+ "<span class=\"return-type\">T</span>&nbsp;<span class=\"member-name\">foo</span>&#8203;"
+ "(<span class=\"arguments\">T&nbsp;t)</span></div>");
+ "(<span class=\"parameters\">T&nbsp;t)</span></div>");

//==============================================================
// Test Class-Use Documentation for Type Parameters.
@@ -562,14 +562,14 @@ void checkAnnotationTypeUsage() {
// METHOD PARAMS
"<div class=\"member-signature\"><span class=\"modifiers\">public</span>&nbsp;<span "
+ "class=\"return-type\">void</span>&nbsp;<span class=\"member-name\">methodWithParams</span>"
+ "&#8203;(<span class=\"arguments\"><a href=\"AnnotationType.html\" title=\"annotation in pkg\">"
+ "&#8203;(<span class=\"parameters\"><a href=\"AnnotationType.html\" title=\"annotation in pkg\">"
+ "@AnnotationType</a>(<a href=\"AnnotationType.html#optional()\">optional</a>"
+ "=\"Parameter Annotation\",<a href=\"AnnotationType.html#required()\">required</a>=1994)\n"
+ "int&nbsp;documented,\n"
+ "int&nbsp;undocmented)</span></div>",
// CONSTRUCTOR PARAMS
"<div class=\"member-signature\"><span class=\"modifiers\">public</span>&nbsp;"
+ "<span class=\"member-name\">AnnotationTypeUsage</span>&#8203;(<span class=\"arguments\">"
+ "<span class=\"member-name\">AnnotationTypeUsage</span>&#8203;(<span class=\"parameters\">"
+ "<a href=\"AnnotationType.html\" title=\"annotation in pkg\">@AnnotationType</a>("
+ "<a href=\"AnnotationType.html#optional()\">optional</a>=\"Constructor Param Annotation\","
+ "<a href=\"AnnotationType.html#required()\">required</a>=1994)\n"
@@ -71,7 +71,7 @@ public void testDefault() {
// Method is documented as though it is declared in the inheriting method.
"<div class=\"member-signature\"><span class=\"modifiers\">public</span>&nbsp;"
+ "<span class=\"return-type\">void</span>&nbsp;<span class=\"member-name\">"
+ "methodInheritedFromParent</span>&#8203;(<span class=\"arguments\">int&nbsp;p1)</span>\n"
+ "methodInheritedFromParent</span>&#8203;(<span class=\"parameters\">int&nbsp;p1)</span>\n"
+ " throws <span class=\"exceptions\">java.lang.Exception</span></div>",
"<dl class=\"notes\">\n"
+ "<dt>All Implemented Interfaces:</dt>\n"
@@ -436,7 +436,7 @@ void testAnnotations(Path base, Set<ElementType> types) throws IOException {
+ "<span class=\"modifiers\">private final</span>&nbsp;<span class=\"return-type\">int</span>"
+ "&nbsp;<span class=\"member-name\">i</span></div>",
"<div class=\"member-signature\"><span class=\"modifiers\">public</span>&nbsp;<span class=\"member-name\">R</span>"
+ "&#8203;(<span class=\"arguments\">"
+ "&#8203;(<span class=\"parameters\">"
+ pAnno
+ "int&nbsp;i)</span></div>",
"<div class=\"member-signature\">"

0 comments on commit 87805d9

Please sign in to comment.