8157987: overview-summary.html generated by javadoc should include module information
Reviewed-by: jjg, ksrini
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java Wed Jul 05 21:55:11 2017 +0200
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java Tue Jul 05 13:30:40 2016 -0700
@@ -153,7 +153,11 @@
FrameOutputWriter.generate(configuration);
if (configuration.createoverview) {
- PackageIndexWriter.generate(configuration);
+ if (configuration.showModules) {
+ ModuleIndexWriter.generate(configuration);
+ } else {
+ PackageIndexWriter.generate(configuration);
+ }
}
if (configuration.helpfile.length() == 0 &&
!configuration.nohelp) {
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleIndexWriter.java Tue Jul 05 13:30:40 2016 -0700
@@ -0,0 +1,289 @@
+/*
+ * 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 jdk.javadoc.internal.doclets.formats.html;
+
+import java.io.*;
+import java.util.*;
+
+import javax.lang.model.element.ModuleElement;
+import javax.lang.model.element.PackageElement;
+
+import jdk.javadoc.doclet.DocletEnvironment;
+import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
+import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
+import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
+import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
+import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
+import jdk.javadoc.internal.doclets.toolkit.Content;
+import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
+import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
+import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException;
+import jdk.javadoc.internal.doclets.toolkit.util.Group;
+
+/**
+ * Generate the module index page "overview-summary.html" for the right-hand
+ * frame.
+ *
+ * <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.
+ * This code and its internal interfaces are subject to change or
+ * deletion without notice.</b>
+ *
+ * @author Bhavesh Patel
+ */
+public class ModuleIndexWriter extends AbstractModuleIndexWriter {
+
+ /**
+ * Set representing the modules.
+ *
+ * @see Group
+ */
+ private final SortedSet<ModuleElement> modules;
+
+ /**
+ * HTML tree for main tag.
+ */
+ private HtmlTree htmlTree = HtmlTree.MAIN();
+
+ /**
+ * Construct the ModuleIndexWriter.
+ * @param configuration the configuration object
+ * @param filename the name of the generated file
+ * @throws java.io.IOException
+ */
+ public ModuleIndexWriter(ConfigurationImpl configuration, DocPath filename) throws IOException {
+ super(configuration, filename);
+ modules = configuration.modules;
+ }
+
+ /**
+ * Generate the module index page for the right-hand frame.
+ *
+ * @param configuration the current configuration of the doclet.
+ */
+ public static void generate(ConfigurationImpl configuration) {
+ ModuleIndexWriter mdlgen;
+ DocPath filename = DocPaths.OVERVIEW_SUMMARY;
+ try {
+ mdlgen = new ModuleIndexWriter(configuration, filename);
+ mdlgen.buildModuleIndexFile("doclet.Window_Overview_Summary", true);
+ mdlgen.close();
+ } catch (IOException exc) {
+ configuration.standardmessage.error(
+ "doclet.exception_encountered",
+ exc.toString(), filename);
+ throw new DocletAbortException(exc);
+ }
+ }
+
+ /**
+ * Add the module index.
+ *
+ * @param body the documentation tree to which the index will be added
+ */
+ protected void addIndex(Content body) {
+ if (modules != null && !modules.isEmpty()) {
+ addIndexContents(configuration.getText("doclet.Modules"),
+ configuration.getText("doclet.Member_Table_Summary",
+ configuration.getText("doclet.Module_Summary"),
+ configuration.getText("doclet.modules")), body);
+ }
+ }
+
+ /**
+ * Adds module index contents.
+ *
+ * @param title the title of the section
+ * @param tableSummary summary for the table
+ * @param body the document tree to which the index contents will be added
+ */
+ protected void addIndexContents(String title, String tableSummary, Content body) {
+ HtmlTree htmltree = (configuration.allowTag(HtmlTag.NAV))
+ ? HtmlTree.NAV()
+ : new HtmlTree(HtmlTag.DIV);
+ htmltree.addStyle(HtmlStyle.indexNav);
+ HtmlTree ul = new HtmlTree(HtmlTag.UL);
+ addAllClassesLink(ul);
+ if (configuration.showModules) {
+ addAllModulesLink(ul);
+ }
+ htmltree.addContent(ul);
+ body.addContent(htmltree);
+ addModulesList(title, tableSummary, body);
+ }
+
+ /**
+ * Add the list of modules.
+ *
+ * @param text The table caption
+ * @param tableSummary the summary of the table tag
+ * @param body the content tree to which the module list will be added
+ */
+ protected void addModulesList(String text, String tableSummary, Content body) {
+ Content table = (configuration.isOutputHtml5())
+ ? HtmlTree.TABLE(HtmlStyle.overviewSummary, getTableCaption(new RawHtml(text)))
+ : HtmlTree.TABLE(HtmlStyle.overviewSummary, tableSummary, getTableCaption(new RawHtml(text)));
+ table.addContent(getSummaryTableHeader(moduleTableHeader, "col"));
+ Content tbody = new HtmlTree(HtmlTag.TBODY);
+ addModulesList(tbody);
+ table.addContent(tbody);
+ Content div = HtmlTree.DIV(HtmlStyle.contentContainer, table);
+ if (configuration.allowTag(HtmlTag.MAIN)) {
+ htmlTree.addContent(div);
+ } else {
+ body.addContent(div);
+ }
+ }
+
+ /**
+ * Adds list of modules in the index table. Generate link to each module.
+ *
+ * @param tbody the documentation tree to which the list will be added
+ */
+ protected void addModulesList(Content tbody) {
+ boolean altColor = true;
+ for (ModuleElement mdle : modules) {
+ if (!mdle.isUnnamed()) {
+ Content moduleLinkContent = getModuleLink(mdle, new StringContent(mdle.getQualifiedName().toString()));
+ Content tdModule = HtmlTree.TD(HtmlStyle.colFirst, moduleLinkContent);
+ HtmlTree tdSummary = new HtmlTree(HtmlTag.TD);
+ tdSummary.addStyle(HtmlStyle.colLast);
+ addSummaryComment(mdle, tdSummary);
+ HtmlTree tr = HtmlTree.TR(tdModule);
+ tr.addContent(tdSummary);
+ tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor);
+ tbody.addContent(tr);
+ }
+ altColor = !altColor;
+ }
+ }
+
+ /**
+ * Adds the overview summary comment for this documentation. Add one line
+ * summary at the top of the page and generate a link to the description,
+ * which is added at the end of this page.
+ *
+ * @param body the documentation tree to which the overview header will be added
+ */
+ protected void addOverviewHeader(Content body) {
+ addConfigurationTitle(body);
+ if (!utils.getBody(configuration.overviewElement).isEmpty()) {
+ HtmlTree subTitleDiv = new HtmlTree(HtmlTag.DIV);
+ subTitleDiv.addStyle(HtmlStyle.subTitle);
+ addSummaryComment(configuration.overviewElement, subTitleDiv);
+ Content div = HtmlTree.DIV(HtmlStyle.header, subTitleDiv);
+ Content see = seeLabel;
+ see.addContent(" ");
+ Content descPara = HtmlTree.P(see);
+ Content descLink = getHyperLink(getDocLink(
+ SectionName.OVERVIEW_DESCRIPTION),
+ descriptionLabel, "", "");
+ descPara.addContent(descLink);
+ div.addContent(descPara);
+ if (configuration.allowTag(HtmlTag.MAIN)) {
+ htmlTree.addContent(div);
+ } else {
+ body.addContent(div);
+ }
+ }
+ }
+
+ /**
+ * Adds the overview comment as provided in the file specified by the
+ * "-overview" option on the command line.
+ *
+ * @param htmltree the documentation tree to which the overview comment will
+ * be added
+ */
+ protected void addOverviewComment(Content htmltree) {
+ if (!utils.getBody(configuration.overviewElement).isEmpty()) {
+ htmltree.addContent(getMarkerAnchor(SectionName.OVERVIEW_DESCRIPTION));
+ addInlineComment(configuration.overviewElement, htmltree);
+ }
+ }
+
+ /**
+ * Adds the tag information as provided in the file specified by the
+ * "-overview" option on the command line.
+ *
+ * @param body the documentation tree to which the overview will be added
+ * @throws java.io.IOException
+ */
+ protected void addOverview(Content body) throws IOException {
+ HtmlTree div = new HtmlTree(HtmlTag.DIV);
+ div.addStyle(HtmlStyle.contentContainer);
+ addOverviewComment(div);
+ if (configuration.allowTag(HtmlTag.MAIN)) {
+ htmlTree.addContent(div);
+ body.addContent(htmlTree);
+ } else {
+ body.addContent(div);
+ }
+ }
+
+ /**
+ * Adds the top text (from the -top option), the upper
+ * navigation bar, and then the title (from the"-title"
+ * option), at the top of page.
+ *
+ * @param body the documentation tree to which the navigation bar header will be added
+ */
+ protected void addNavigationBarHeader(Content body) {
+ Content htmlTree = (configuration.allowTag(HtmlTag.HEADER))
+ ? HtmlTree.HEADER()
+ : body;
+ addTop(htmlTree);
+ addNavLinks(true, htmlTree);
+ if (configuration.allowTag(HtmlTag.HEADER)) {
+ body.addContent(htmlTree);
+ }
+ }
+
+ /**
+ * Adds the lower navigation bar and the bottom text
+ * (from the -bottom option) at the bottom of page.
+ *
+ * @param body the documentation tree to which the navigation bar footer will be added
+ */
+ protected void addNavigationBarFooter(Content body) {
+ Content htmltree = (configuration.allowTag(HtmlTag.FOOTER))
+ ? HtmlTree.FOOTER()
+ : body;
+ addNavLinks(false, htmltree);
+ addBottom(htmltree);
+ if (configuration.allowTag(HtmlTag.FOOTER)) {
+ body.addContent(htmltree);
+ }
+ }
+
+ protected void addModulePackagesList(Map<ModuleElement, Set<PackageElement>> modules, String text,
+ String tableSummary, Content body, ModuleElement mdle) {
+ }
+
+ protected void addModulesList(Map<ModuleElement, Set<PackageElement>> modules, String text,
+ String tableSummary, Content body) {
+ }
+}
--- a/langtools/test/jdk/javadoc/doclet/testModules/TestModules.java Wed Jul 05 21:55:11 2017 +0200
+++ b/langtools/test/jdk/javadoc/doclet/testModules/TestModules.java Tue Jul 05 13:30:40 2016 -0700
@@ -23,7 +23,7 @@
/*
* @test
- * @bug 8154119 8154262 8156077
+ * @bug 8154119 8154262 8156077 8157987
* @summary Test modules support in javadoc.
* @author bpatel
* @library ../lib
@@ -48,6 +48,7 @@
checkExit(Exit.OK);
testDescription(true);
testNoDescription(false);
+ testOverviewSummaryModules();
testModuleLink();
}
@@ -60,6 +61,7 @@
checkExit(Exit.OK);
testHtml5Description(true);
testHtml5NoDescription(false);
+ testHtml5OverviewSummaryModules();
testModuleLink();
}
@@ -91,8 +93,9 @@
void test5() {
javadoc("-d", "out-nomodule", "-use",
"-sourcepath", testSrc,
- "testpkgnomodule");
+ "testpkgnomodule", "testpkgnomodule1");
checkExit(Exit.OK);
+ testOverviewSummaryPackages();
}
@Test
@@ -107,6 +110,15 @@
testModuleTags();
}
+ @Test
+ void test8() {
+ javadoc("-d", "out-html5-nomodule", "-html5", "-use",
+ "-sourcepath", testSrc,
+ "testpkgnomodule", "testpkgnomodule1");
+ checkExit(Exit.OK);
+ testHtml5OverviewSummaryPackages();
+ }
+
void testDescription(boolean found) {
checkOutput("module1-summary.html", found,
"<!-- ============ MODULE DESCRIPTION =========== -->\n"
@@ -233,4 +245,72 @@
"<dt><span class=\"simpleTagLabel\">Module Tag:</span></dt>\n"
+ "<dd>Just a simple module tag.</dd>");
}
+
+ void testOverviewSummaryModules() {
+ checkOutput("overview-summary.html", true,
+ "<table class=\"overviewSummary\" summary=\"Module Summary table, listing modules, and an explanation\">\n"
+ + "<caption><span>Modules</span><span class=\"tabEnd\"> </span></caption>\n"
+ + "<tr>\n"
+ + "<th class=\"colFirst\" scope=\"col\">Module</th>\n"
+ + "<th class=\"colLast\" scope=\"col\">Description</th>\n"
+ + "</tr>");
+ checkOutput("overview-summary.html", false,
+ "<table class=\"overviewSummary\" summary=\"Packages table, listing packages, and an explanation\">\n"
+ + "<caption><span>Packages</span><span class=\"tabEnd\"> </span></caption>\n"
+ + "<tr>\n"
+ + "<th class=\"colFirst\" scope=\"col\">Package</th>\n"
+ + "<th class=\"colLast\" scope=\"col\">Description</th>\n"
+ + "</tr>");
+ }
+
+ void testOverviewSummaryPackages() {
+ checkOutput("overview-summary.html", false,
+ "<table class=\"overviewSummary\" summary=\"Module Summary table, listing modules, and an explanation\">\n"
+ + "<caption><span>Modules</span><span class=\"tabEnd\"> </span></caption>\n"
+ + "<tr>\n"
+ + "<th class=\"colFirst\" scope=\"col\">Module</th>\n"
+ + "<th class=\"colLast\" scope=\"col\">Description</th>\n"
+ + "</tr>");
+ checkOutput("overview-summary.html", true,
+ "<table class=\"overviewSummary\" summary=\"Packages table, listing packages, and an explanation\">\n"
+ + "<caption><span>Packages</span><span class=\"tabEnd\"> </span></caption>\n"
+ + "<tr>\n"
+ + "<th class=\"colFirst\" scope=\"col\">Package</th>\n"
+ + "<th class=\"colLast\" scope=\"col\">Description</th>\n"
+ + "</tr>");
+ }
+
+ void testHtml5OverviewSummaryModules() {
+ checkOutput("overview-summary.html", true,
+ "<table class=\"overviewSummary\">\n"
+ + "<caption><span>Modules</span><span class=\"tabEnd\"> </span></caption>\n"
+ + "<tr>\n"
+ + "<th class=\"colFirst\" scope=\"col\">Module</th>\n"
+ + "<th class=\"colLast\" scope=\"col\">Description</th>\n"
+ + "</tr>");
+ checkOutput("overview-summary.html", false,
+ "<table class=\"overviewSummary\">\n"
+ + "<caption><span>Packages</span><span class=\"tabEnd\"> </span></caption>\n"
+ + "<tr>\n"
+ + "<th class=\"colFirst\" scope=\"col\">Package</th>\n"
+ + "<th class=\"colLast\" scope=\"col\">Description</th>\n"
+ + "</tr>");
+ }
+
+ void testHtml5OverviewSummaryPackages() {
+ checkOutput("overview-summary.html", false,
+ "<table class=\"overviewSummary\">\n"
+ + "<caption><span>Modules</span><span class=\"tabEnd\"> </span></caption>\n"
+ + "<tr>\n"
+ + "<th class=\"colFirst\" scope=\"col\">Module</th>\n"
+ + "<th class=\"colLast\" scope=\"col\">Description</th>\n"
+ + "</tr>");
+ checkOutput("overview-summary.html", true,
+ "<table class=\"overviewSummary\">\n"
+ + "<caption><span>Packages</span><span class=\"tabEnd\"> </span></caption>\n"
+ + "<tr>\n"
+ + "<th class=\"colFirst\" scope=\"col\">Package</th>\n"
+ + "<th class=\"colLast\" scope=\"col\">Description</th>\n"
+ + "</tr>");
+ }
}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/jdk/javadoc/doclet/testModules/testpkgnomodule1/TestClassNoModulePkg1.java Tue Jul 05 13:30:40 2016 -0700
@@ -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 testpkgnomodule1;
+
+public class TestClassNoModulePkg1 {
+}