changeset 3362:53d10f55a055

8154119: Module summary page should display module description Reviewed-by: jjg
author bpatel
date Thu, 28 Apr 2016 05:10:11 +0000
parents 77864d84ccb5
children 8d8d8069aaef
files src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SectionName.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlConstants.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ModuleSummaryWriter.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ModuleSummaryBuilder.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclet.xml test/jdk/javadoc/doclet/testModules/TestModules.java test/jdk/javadoc/doclet/testModules/module1/module-info.java test/jdk/javadoc/doclet/testModules/module1/testpkgmdl1/TestClassInModule1.java test/jdk/javadoc/doclet/testModules/module2/module-info.java test/jdk/javadoc/doclet/testModules/module2/testpkgmdl2/TestClassInModule2.java
diffstat 11 files changed, 311 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java	Wed Apr 27 19:56:44 2016 -0700
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java	Thu Apr 28 05:10:11 2016 +0000
@@ -168,6 +168,21 @@
     }
 
     /**
+     * {@inheritDoc}
+     */
+    public void addModuleDescription(Content moduleContentTree) {
+        if (!utils.getBody(mdle).isEmpty()) {
+            Content tree = configuration.allowTag(HtmlTag.SECTION) ? HtmlTree.SECTION() : moduleContentTree;
+            tree.addContent(HtmlConstants.START_OF_MODULE_DESCRIPTION);
+            tree.addContent(getMarkerAnchor(SectionName.MODULE_DESCRIPTION));
+            addInlineComment(mdle, tree);
+            if (configuration.allowTag(HtmlTag.SECTION)) {
+                moduleContentTree.addContent(tree);
+            }
+        }
+    }
+
+    /**
      * Adds list of packages in the package summary table. Generate link to each package.
      *
      * @param packages Packages to which link is to be generated
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SectionName.java	Wed Apr 27 19:56:44 2016 -0700
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SectionName.java	Thu Apr 28 05:10:11 2016 +0000
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2016, 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
@@ -53,6 +53,7 @@
     METHOD_DETAIL("method.detail"),
     METHODS_INHERITANCE("methods.inherited.from.class."),
     METHOD_SUMMARY("method.summary"),
+    MODULE_DESCRIPTION("module.description"),
     NAVBAR_BOTTOM("navbar.bottom"),
     NAVBAR_BOTTOM_FIRSTROW("navbar.bottom.firstrow"),
     NAVBAR_TOP("navbar.top"),
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlConstants.java	Wed Apr 27 19:56:44 2016 -0700
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlConstants.java	Thu Apr 28 05:10:11 2016 +0000
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2016, 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
@@ -64,6 +64,12 @@
             new Comment("======== END OF BOTTOM NAVBAR =======");
 
     /**
+     * Marker to identify start of module description.
+     */
+    public static final Content START_OF_MODULE_DESCRIPTION =
+            new Comment("============ MODULE DESCRIPTION ===========");
+
+    /**
      * Marker to identify start of class data.
      */
     public static final Content START_OF_CLASS_DATA =
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ModuleSummaryWriter.java	Wed Apr 27 19:56:44 2016 -0700
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ModuleSummaryWriter.java	Thu Apr 28 05:10:11 2016 +0000
@@ -74,6 +74,14 @@
     public abstract Content getSummaryTree(Content summaryContentTree);
 
     /**
+     * Adds the module description.
+     *
+     * @param moduleContentTree the content tree to which the module description
+     *                           will be added
+     */
+    public abstract void addModuleDescription(Content moduleContentTree);
+
+    /**
      * Adds the table of packages to the documentation tree.
      *
      * @param packages the set of packages that should be added.
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ModuleSummaryBuilder.java	Wed Apr 27 19:56:44 2016 -0700
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ModuleSummaryBuilder.java	Thu Apr 28 05:10:11 2016 +0000
@@ -185,4 +185,17 @@
                     packageTableSummary, summaryContentTree);
         }
     }
+
+    /**
+     * Build the description for the module.
+     *
+     * @param node the XML element that specifies which components to document
+     * @param moduleContentTree the tree to which the module description will
+     *                           be added
+     */
+    public void buildModuleDescription(XMLNode node, Content moduleContentTree) {
+        if (!configuration.nocomment) {
+            moduleWriter.addModuleDescription(moduleContentTree);
+        }
+    }
 }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclet.xml	Wed Apr 27 19:56:44 2016 -0700
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclet.xml	Thu Apr 28 05:10:11 2016 +0000
@@ -30,6 +30,7 @@
 
     <ModuleDoc>
         <Content>
+            <ModuleDescription/>
             <Summary>
                 <PackageSummary/>
             </Summary>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/jdk/javadoc/doclet/testModules/TestModules.java	Thu Apr 28 05:10:11 2016 +0000
@@ -0,0 +1,145 @@
+/*
+ * Copyright (c) 2016, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug 8154119
+ * @summary Test modules support in javadoc.
+ * @author bpatel
+ * @library ../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build JavadocTester
+ * @run main TestModules
+ */
+
+public class TestModules extends JavadocTester {
+
+    public static void main(String... args) throws Exception {
+        TestModules tester = new TestModules();
+        tester.runTests();
+    }
+
+    @Test
+    void test1() {
+        javadoc("-d", "out",
+                "-modulesourcepath", testSrc,
+                "-addmods", "module1,module2",
+                "testpkgmdl1", "testpkgmdl2");
+        checkExit(Exit.OK);
+        testDescription(true);
+        testNoDescription(false);
+    }
+
+    @Test
+    void test2() {
+        javadoc("-d", "out-html5", "-html5",
+                "-modulesourcepath", testSrc,
+                "-addmods", "module1,module2",
+                "testpkgmdl1", "testpkgmdl2");
+        checkExit(Exit.OK);
+        testHtml5Description(true);
+        testHtml5NoDescription(false);
+    }
+
+    @Test
+    void test3() {
+        javadoc("-d", "out-nocomment", "-nocomment",
+                "-modulesourcepath", testSrc,
+                "-addmods", "module1,module2",
+                "testpkgmdl1", "testpkgmdl2");
+        checkExit(Exit.OK);
+        testDescription(false);
+        testNoDescription(true);
+    }
+
+    @Test
+    void test4() {
+        javadoc("-d", "out-html5-nocomment", "-nocomment", "-html5",
+                "-modulesourcepath", testSrc,
+                "-addmods", "module1,module2",
+                "testpkgmdl1", "testpkgmdl2");
+        checkExit(Exit.OK);
+        testHtml5Description(false);
+        testHtml5NoDescription(true);
+    }
+
+    void testDescription(boolean found) {
+        checkOutput("module1-summary.html", found,
+                "<!-- ============ MODULE DESCRIPTION =========== -->\n"
+                + "<a name=\"module.description\">\n"
+                + "<!--   -->\n"
+                + "</a>\n"
+                + "<div class=\"block\">This is a test description for the module1 module.</div>");
+        checkOutput("module2-summary.html", found,
+                "<!-- ============ MODULE DESCRIPTION =========== -->\n"
+                + "<a name=\"module.description\">\n"
+                + "<!--   -->\n"
+                + "</a>\n"
+                + "<div class=\"block\">This is a test description for the module2 module.</div>");
+    }
+
+    void testNoDescription(boolean found) {
+        checkOutput("module1-summary.html", found,
+                "<div class=\"contentContainer\">\n"
+                + "<ul class=\"blockList\">\n"
+                + "<li class=\"blockList\">\n"
+                + "<table class=\"overviewSummary\" summary=\"Package Summary table, listing packages, and an explanation\">");
+        checkOutput("module2-summary.html", found,
+                "<div class=\"contentContainer\">\n"
+                + "<ul class=\"blockList\">\n"
+                + "<li class=\"blockList\">\n"
+                + "<table class=\"overviewSummary\" summary=\"Package Summary table, listing packages, and an explanation\">");
+    }
+
+    void testHtml5Description(boolean found) {
+        checkOutput("module1-summary.html", found,
+                "<section role=\"region\">\n"
+                + "<!-- ============ MODULE DESCRIPTION =========== -->\n"
+                + "<a id=\"module.description\">\n"
+                + "<!--   -->\n"
+                + "</a>\n"
+                + "<div class=\"block\">This is a test description for the module1 module.</div>\n"
+                + "</section>");
+        checkOutput("module2-summary.html", found,
+                "<section role=\"region\">\n"
+                + "<!-- ============ MODULE DESCRIPTION =========== -->\n"
+                + "<a id=\"module.description\">\n"
+                + "<!--   -->\n"
+                + "</a>\n"
+                + "<div class=\"block\">This is a test description for the module2 module.</div>\n"
+                + "</section>");
+    }
+
+    void testHtml5NoDescription(boolean found) {
+        checkOutput("module1-summary.html", found,
+                "<div class=\"contentContainer\">\n"
+                + "<ul class=\"blockList\">\n"
+                + "<li class=\"blockList\">\n"
+                + "<table class=\"overviewSummary\">");
+        checkOutput("module2-summary.html", found,
+                "<div class=\"contentContainer\">\n"
+                + "<ul class=\"blockList\">\n"
+                + "<li class=\"blockList\">\n"
+                + "<table class=\"overviewSummary\">");
+    }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/jdk/javadoc/doclet/testModules/module1/module-info.java	Thu Apr 28 05:10:11 2016 +0000
@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2016, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+  * This is a test description for the module1 module.
+  */
+module module1 {
+    requires module2;
+
+    exports testpkgmdl1;
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/jdk/javadoc/doclet/testModules/module1/testpkgmdl1/TestClassInModule1.java	Thu Apr 28 05:10:11 2016 +0000
@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2016, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package testpkgmdl1;
+
+public class TestClassInModule1 {
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/jdk/javadoc/doclet/testModules/module2/module-info.java	Thu Apr 28 05:10:11 2016 +0000
@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2016, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+  * This is a test description for the module2 module.
+  */
+module module2 {
+    exports testpkgmdl2;
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/jdk/javadoc/doclet/testModules/module2/testpkgmdl2/TestClassInModule2.java	Thu Apr 28 05:10:11 2016 +0000
@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2016, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package testpkgmdl2;
+
+public class TestClassInModule2 {
+}