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

…gnature

Reviewed-by: hannesw

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java

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

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

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

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

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

test/langtools/jdk/javadoc/doclet/testIndentation/TestIndentation.java

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

test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFX.java

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

test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java

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

test/langtools/jdk/javadoc/doclet/testMethodSignature/TestMethodSignature.java

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

test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java

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

test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java

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

test/langtools/jdk/javadoc/doclet/testRecordTypes/TestRecordTypes.java

@@ -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\">"