changeset 3694:6842e63d6c39 jdk-9+140

4649116: Add option to include full package description at top, before interface table Reviewed-by: jjg
author bpatel
date Mon, 10 Oct 2016 15:17:02 -0700
parents 87b48a8fb3cf
children d83a8e24bbb0 40468274ff3b
files src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclet.xml test/jdk/javadoc/doclet/testHtmlTag/TestHtmlTag.java test/jdk/javadoc/doclet/testHtmlVersion/TestHtmlVersion.java
diffstat 5 files changed, 32 insertions(+), 37 deletions(-) [+]
line wrap: on
line diff
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java	Mon Oct 10 11:21:00 2016 -0700
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java	Mon Oct 10 15:17:02 2016 -0700
@@ -143,19 +143,6 @@
         Content packageHead = new StringContent(heading);
         tHeading.addContent(packageHead);
         div.addContent(tHeading);
-        addDeprecationInfo(div);
-        if (!utils.getFullBody(packageElement).isEmpty() && !configuration.nocomment) {
-            HtmlTree docSummaryDiv = new HtmlTree(HtmlTag.DIV);
-            docSummaryDiv.addStyle(HtmlStyle.docSummary);
-            addSummaryComment(packageElement, docSummaryDiv);
-            div.addContent(docSummaryDiv);
-            Content space = Contents.SPACE;
-            Content descLink = getHyperLink(getDocLink(
-                    SectionName.PACKAGE_DESCRIPTION),
-                    contents.descriptionLabel, "", "");
-            Content descPara = new HtmlTree(HtmlTag.P, contents.seeLabel, space, descLink);
-            div.addContent(descPara);
-        }
         if (configuration.allowTag(HtmlTag.MAIN)) {
             mainTree.addContent(div);
         } else {
@@ -258,20 +245,10 @@
      */
     @Override
     public void addPackageDescription(Content packageContentTree) {
-        if (!utils.getFullBody(packageElement).isEmpty()) {
-            packageContentTree.addContent(
-                    getMarkerAnchor(SectionName.PACKAGE_DESCRIPTION));
-            Content h2Content = new StringContent(
-                    configuration.getText("doclet.Package_Description",
-                    packageElement.isUnnamed() ? "" : utils.getPackageName(packageElement)));
-            Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true, h2Content);
-            if (configuration.allowTag(HtmlTag.SECTION)) {
-                sectionTree.addContent(heading);
-                addInlineComment(packageElement, sectionTree);
-            } else {
-                packageContentTree.addContent(heading);
-                addInlineComment(packageElement, packageContentTree);
-            }
+        if (!utils.getBody(packageElement).isEmpty()) {
+            Content tree = configuration.allowTag(HtmlTag.SECTION) ? sectionTree : packageContentTree;
+            addDeprecationInfo(tree);
+            addInlineComment(packageElement, tree);
         }
     }
 
@@ -284,6 +261,9 @@
                 ? sectionTree
                 : packageContentTree;
         addTagsInfo(packageElement, htmlTree);
+        if (configuration.allowTag(HtmlTag.SECTION)) {
+            packageContentTree.addContent(sectionTree);
+        }
     }
 
     /**
@@ -292,7 +272,6 @@
     @Override
     public void addPackageContent(Content contentTree, Content packageContentTree) {
         if (configuration.allowTag(HtmlTag.MAIN)) {
-            packageContentTree.addContent(sectionTree);
             mainTree.addContent(packageContentTree);
             contentTree.addContent(mainTree);
         } else {
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties	Mon Oct 10 11:21:00 2016 -0700
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties	Mon Oct 10 15:17:02 2016 -0700
@@ -97,7 +97,6 @@
 doclet.deprecated_annotation_type_members=deprecated annotation type elements
 doclet.Generated_Docs_Untitled=Generated Documentation (Untitled)
 doclet.Other_Packages=Other Packages
-doclet.Package_Description=Package {0} Description
 doclet.Description=Description
 doclet.Specified_By=Specified by:
 doclet.in_interface=in interface
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclet.xml	Mon Oct 10 11:21:00 2016 -0700
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclet.xml	Mon Oct 10 15:17:02 2016 -0700
@@ -42,6 +42,8 @@
 
     <PackageDoc>
         <Content>
+            <PackageDescription/>
+            <PackageTags/>
             <Summary>
                 <InterfaceSummary/>
                 <ClassSummary/>
@@ -50,8 +52,6 @@
                 <ErrorSummary/>
                 <AnnotationTypeSummary/>
             </Summary>
-            <PackageDescription/>
-            <PackageTags/>
         </Content>
     </PackageDoc>
 
--- a/test/jdk/javadoc/doclet/testHtmlTag/TestHtmlTag.java	Mon Oct 10 11:21:00 2016 -0700
+++ b/test/jdk/javadoc/doclet/testHtmlTag/TestHtmlTag.java	Mon Oct 10 15:17:02 2016 -0700
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 6786682
+ * @bug 6786682 4649116
  * @summary This test verifies the use of lang attribute by <HTML>.
  * @author Bhavesh Patel
  * @library ../lib
@@ -106,7 +106,7 @@
         checkExit(Exit.OK);
 
         checkOutput("pkg3/package-summary.html", true,
-                "<h2 title=\"Package pkg3 Description\">Package pkg3 Description</h2>\n"
+                "<div class=\"contentContainer\">\n"
                 + "<div class=\"block\"><p>This is the first line."
                 + " Note the newlines before the &lt;p&gt; is relevant.</div>");
 
--- a/test/jdk/javadoc/doclet/testHtmlVersion/TestHtmlVersion.java	Mon Oct 10 11:21:00 2016 -0700
+++ b/test/jdk/javadoc/doclet/testHtmlVersion/TestHtmlVersion.java	Mon Oct 10 15:17:02 2016 -0700
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 8072945 8081854 8141492 8148985 8150188
+ * @bug 8072945 8081854 8141492 8148985 8150188 4649116
  * @summary Test the version of HTML generated by the javadoc tool.
  * @author bpatel
  * @library ../lib
@@ -162,10 +162,17 @@
                 "<main role=\"main\">\n"
                 + "<div class=\"header\">",
                 "<section role=\"region\">\n"
-                + "<h2 title=\"Package pkg Description\">Package pkg Description</h2>\n",
+                + "<div class=\"block\">Test package.</div>",
                 "<footer role=\"contentinfo\">\n"
                 + "<nav role=\"navigation\">\n"
                 + "<!-- ======= START OF BOTTOM NAVBAR ====== -->");
+        // No package description
+        checkOutput("pkg1/package-summary.html", true,
+                "<div class=\"contentContainer\">\n"
+                + "<ul class=\"blockList\">\n"
+                + "<li class=\"blockList\">\n"
+                + "<table class=\"typeSummary\">\n"
+                + "<caption><span>Class Summary</span><span class=\"tabEnd\">&nbsp;</span></caption>");
 
         // Test for package-tree page
         checkOutput("pkg/package-tree.html", true,
@@ -662,6 +669,8 @@
                 "<a name=\"navbar.top.firstrow\">\n"
                 + "<!--   -->\n"
                 + "</a>",
+                "<section role=\"region\">\n"
+                + "<h2 title=\"Package pkg Description\">Package pkg Description</h2>\n",
                 "<table class=\"typeSummary\" summary=\"Interface Summary table, listing interfaces, and an explanation\">",
                 "<table class=\"typeSummary\" summary=\"Class Summary table, listing classes, and an explanation\">",
                 "<table class=\"typeSummary\" summary=\"Enum Summary table, listing enums, and an explanation\">",
@@ -1060,12 +1069,21 @@
                 "<a name=\"navbar.top.firstrow\">\n"
                 + "<!--   -->\n"
                 + "</a>",
+                "<div class=\"contentContainer\">\n"
+                + "<div class=\"block\">Test package.</div>",
                 "<table class=\"typeSummary\" summary=\"Interface Summary table, listing interfaces, and an explanation\">",
                 "<table class=\"typeSummary\" summary=\"Class Summary table, listing classes, and an explanation\">",
                 "<table class=\"typeSummary\" summary=\"Enum Summary table, listing enums, and an explanation\">",
                 "<table class=\"typeSummary\" summary=\"Exception Summary table, listing exceptions, and an explanation\">",
                 "<table class=\"typeSummary\" summary=\"Error Summary table, listing errors, and an explanation\">",
                 "<table class=\"typeSummary\" summary=\"Annotation Types Summary table, listing annotation types, and an explanation\">");
+        // No Package description
+        checkOutput("pkg1/package-summary.html", true,
+                "<div class=\"contentContainer\">\n"
+                + "<ul class=\"blockList\">\n"
+                + "<li class=\"blockList\">\n"
+                + "<table class=\"typeSummary\" summary=\"Class Summary table, listing classes, and an explanation\">\n"
+                + "<caption><span>Class Summary</span><span class=\"tabEnd\">&nbsp;</span></caption>");
 
         // Test for package-tree page
         checkOutput("pkg/package-tree.html", true,
@@ -1485,8 +1503,7 @@
                 + "<!-- ========= START OF TOP NAVBAR ======= -->",
                 "<main role=\"main\">\n"
                 + "<div class=\"header\">",
-                "<section role=\"region\">\n"
-                + "<h2 title=\"Package pkg Description\">Package pkg Description</h2>\n",
+                "<h2 title=\"Package pkg Description\">Package pkg Description</h2>\n",
                 "<footer role=\"contentinfo\">\n"
                 + "<nav role=\"navigation\">\n"
                 + "<!-- ======= START OF BOTTOM NAVBAR ====== -->");