8156077: Support javadoc tags in module documentation

Reviewed-by: jjg

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java

@@ -87,6 +87,8 @@ public interface Taglet {
     public static enum Location {
         /** In an Overview document. */
         OVERVIEW,
+        /** In the documentation for a module. */
+        MODULE,
         /** In the documentation for a package. */
         PACKAGE,
         /** In the documentation for a class, interface or enum. */

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

@@ -182,6 +182,19 @@ public class ModuleWriterImpl extends HtmlDocletWriter implements ModuleSummaryW
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public void addModuleTags(Content moduleContentTree) {
+        Content tree = (configuration.allowTag(HtmlTag.SECTION))
+                ? HtmlTree.SECTION()
+                : moduleContentTree;
+        addTagsInfo(mdle, tree);
+        if (configuration.allowTag(HtmlTag.SECTION)) {
+            moduleContentTree.addContent(tree);
+        }
+    }
+
     /**
      * Adds list of packages in the package summary table. Generate link to each package.
      *

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ModuleSummaryWriter.java

@@ -81,6 +81,15 @@ public interface ModuleSummaryWriter {
      */
     public abstract void addModuleDescription(Content moduleContentTree);
 
+    /**
+     * Adds the tag information from the "module-info.java" file to the documentation
+     * tree.
+     *
+     * @param moduleContentTree the content tree to which the module tags will
+     *                           be added
+     */
+    public abstract void addModuleTags(Content moduleContentTree);
+
     /**
      * Adds the table of packages to the documentation tree.
      *

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ModuleSummaryBuilder.java

@@ -198,4 +198,16 @@ public class ModuleSummaryBuilder extends AbstractBuilder {
             moduleWriter.addModuleDescription(moduleContentTree);
         }
     }
+
+    /**
+     * Build the tags of the summary.
+     *
+     * @param node the XML element that specifies which components to document
+     * @param moduleContentTree the tree to which the module tags will be added
+     */
+    public void buildModuleTags(XMLNode node, Content moduleContentTree) {
+        if (!configuration.nocomment) {
+            moduleWriter.addModuleTags(moduleContentTree);
+        }
+    }
 }

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclet.xml

@@ -31,6 +31,7 @@
     <ModuleDoc>
         <Content>
             <ModuleDescription/>
+            <ModuleTags/>
             <Summary>
                 <PackageSummary/>
             </Summary>

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BaseExecutableMemberTaglet.java

@@ -60,6 +60,17 @@ public abstract class BaseExecutableMemberTaglet extends BaseTaglet {
         return false;
     }
 
+    /**
+     * Return true if this <code>Taglet</code>
+     * is used in module documentation.
+     * @return true if this <code>Taglet</code>
+     * is used in module documentation and false
+     * otherwise.
+     */
+    public boolean inModule() {
+        return false;
+    }
+
     /**
      * Return true if this <code>Taglet</code>
      * is used in package documentation.

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BasePropertyTaglet.java

@@ -85,6 +85,15 @@ public abstract class BasePropertyTaglet extends BaseTaglet {
         return false;
     }
 
+    /**
+     * Will return false because this tag may
+     * only appear in Methods.
+     * @return false since this is not a method.
+     */
+    public boolean inModule() {
+        return false;
+    }
+
     /**
      * Will return false because this tag may
      * only appear in Methods.

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BaseTaglet.java

@@ -88,6 +88,17 @@ public abstract class BaseTaglet implements Taglet {
         return true;
     }
 
+    /**
+     * Return true if this <code>Taglet</code>
+     * is used in module documentation.
+     * @return true if this <code>Taglet</code>
+     * is used in module documentation and false
+     * otherwise.
+     */
+    public boolean inModule() {
+        return true;
+    }
+
     /**
      * Return true if this <code>Taglet</code>
      * is used in package documentation.

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java

@@ -93,6 +93,15 @@ public class InheritDocTaglet extends BaseInlineTaglet {
         return false;
     }
 
+    /**
+     * Will return false because this inline tag may
+     * not appear in Modules.
+     * @return false
+     */
+    public boolean inModule() {
+        return false;
+    }
+
     /**
      * Will return false because this inline tag may
      * not appear in Packages.

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java

@@ -149,6 +149,13 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
         return false;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public boolean inModule() {
+        return false;
+    }
+
     /**
      * {@inheritDoc}
      */

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SimpleTaglet.java

@@ -55,6 +55,11 @@ public class SimpleTaglet extends BaseTaglet implements InheritableTaglet {
      */
     public static final String EXCLUDED = "x";
 
+    /**
+     * The marker in the location string for modules.
+     */
+    public static final String MODULE = "s";
+
     /**
      * The marker in the location string for packages.
      */
@@ -120,7 +125,7 @@ public class SimpleTaglet extends BaseTaglet implements InheritableTaglet {
         this.header = header;
         locations = Utils.toLowerCase(locations);
         if (locations.contains(ALL) && !locations.contains(EXCLUDED)) {
-            this.locations = PACKAGE + TYPE + FIELD + METHOD + CONSTRUCTOR + OVERVIEW;
+            this.locations = MODULE + PACKAGE + TYPE + FIELD + METHOD + CONSTRUCTOR + OVERVIEW;
         } else {
             this.locations = locations;
         }
@@ -177,6 +182,17 @@ public class SimpleTaglet extends BaseTaglet implements InheritableTaglet {
         return locations.contains(OVERVIEW) && !locations.contains(EXCLUDED);
     }
 
+    /**
+     * Return true if this <code>SimpleTaglet</code>
+     * is used in module documentation.
+     * @return true if this <code>SimpleTaglet</code>
+     * is used in module documentation and false
+     * otherwise.
+     */
+    public boolean inModule() {
+        return locations.contains(MODULE) && !locations.contains(EXCLUDED);
+    }
+
     /**
      * Return true if this <code>SimpleTaglet</code>
      * is used in package documentation.

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/Taglet.java

@@ -74,6 +74,15 @@ public interface Taglet {
      */
     public abstract boolean inOverview();
 
+    /**
+     * Return true if this <code>Taglet</code>
+     * is used in module documentation.
+     * @return true if this <code>Taglet</code>
+     * is used in module documentation and false
+     * otherwise.
+     */
+    public abstract boolean inModule();
+
     /**
      * Return true if this <code>Taglet</code>
      * is used in package documentation.

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java

@@ -31,6 +31,7 @@ import java.util.*;
 
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
+import javax.lang.model.element.ModuleElement;
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.element.VariableElement;
@@ -80,6 +81,11 @@ public class TagletManager {
      */
     private final LinkedHashMap<String,Taglet> customTags;
 
+    /**
+     * The array of custom tags that can appear in modules.
+     */
+    private List<Taglet> moduleTags;
+
     /**
      * The array of custom tags that can appear in packages.
      */
@@ -372,6 +378,14 @@ public class TagletManager {
                     return;
                 }
                 new SimpleElementVisitor9<Void, Void>() {
+                    @Override @DefinedBy(Api.LANGUAGE_MODEL)
+                    public Void visitModule(ModuleElement e, Void p) {
+                        if (!taglet.inModule()) {
+                            printTagMisuseWarn(utils.getCommentHelper(e), taglet, tag, "module");
+                        }
+                        return null;
+                    }
+
                     @Override @DefinedBy(Api.LANGUAGE_MODEL)
                     public Void visitPackage(PackageElement e, Void p) {
                         if (!taglet.inPackage()) {
@@ -435,6 +449,9 @@ public class TagletManager {
         if (taglet.inOverview()) {
             locationsSet.add("overview");
         }
+        if (taglet.inModule()) {
+            locationsSet.add("module");
+        }
         if (taglet.inPackage()) {
             locationsSet.add("package");
         }
@@ -469,6 +486,19 @@ public class TagletManager {
             "@" + taglet.getName(), holderType, combined_locations.toString());
     }
 
+    /**
+     * Return the array of <code>Taglet</code>s that can
+     * appear in modules.
+     * @return the array of <code>Taglet</code>s that can
+     * appear in modules.
+     */
+    public List<Taglet> getModuleCustomTaglets() {
+        if (moduleTags == null) {
+            initCustomTaglets();
+        }
+        return moduleTags;
+    }
+
     /**
      * Return the array of <code>Taglet</code>s that can
      * appear in packages.
@@ -555,6 +585,8 @@ public class TagletManager {
             case CLASS:
             case ENUM:
                 return getTypeCustomTaglets();
+            case MODULE:
+                return getModuleCustomTaglets();
             case PACKAGE:
                 return getPackageCustomTaglets();
             case OTHER:
@@ -608,6 +640,7 @@ public class TagletManager {
      */
     private void initCustomTaglets() {
 
+        moduleTags = new ArrayList<>();
         packageTags = new ArrayList<>();
         typeTags = new ArrayList<>();
         fieldTags = new ArrayList<>();
@@ -617,6 +650,9 @@ public class TagletManager {
         overviewTags = new ArrayList<>();
 
         for (Taglet current : customTags.values()) {
+            if (current.inModule() && !current.isInlineTag()) {
+                moduleTags.add(current);
+            }
             if (current.inPackage() && !current.isInlineTag()) {
                 packageTags.add(current);
             }
@@ -666,9 +702,9 @@ public class TagletManager {
         addStandardTaglet(!nosince, new SimpleTaglet(SINCE.tagName, message.getText("doclet.Since"),
                 SimpleTaglet.ALL));
         addStandardTaglet(showversion, new SimpleTaglet(VERSION.tagName, message.getText("doclet.Version"),
-                SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
+                SimpleTaglet.MODULE + SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
         addStandardTaglet(showauthor, new SimpleTaglet(AUTHOR.tagName, message.getText("doclet.Author"),
-                SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
+                SimpleTaglet.MODULE + SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
         addStandardTaglet(new SimpleTaglet(SERIAL_DATA.tagName, message.getText("doclet.SerialData"),
                 SimpleTaglet.EXCLUDED));
         addStandardTaglet(new SimpleTaglet(HIDDEN.tagName, message.getText("doclet.Hidden"),

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/UserTaglet.java

@@ -86,6 +86,14 @@ public class UserTaglet implements Taglet {
                 || userTaglet.getAllowedLocations().contains(OVERVIEW);
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public boolean inModule() {
+        return userTaglet.isInlineTag()
+                || userTaglet.getAllowedLocations().contains(MODULE);
+    }
+
     /**
      * {@inheritDoc}
      */

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ValueTaglet.java

@@ -92,6 +92,15 @@ public class ValueTaglet extends BaseInlineTaglet {
         return true;
     }
 
+    /**
+     * Will return false because this inline tag may
+     * only appear in Fields.
+     * @return false since this is not a field.
+     */
+    public boolean inModule() {
+        return false;
+    }
+
     /**
      * Will return false because this inline tag may
      * only appear in Fields.

langtools/test/jdk/javadoc/doclet/testModules/TestModules.java

@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 8154119 8154262
+ * @bug 8154119 8154262 8156077
  * @summary Test modules support in javadoc.
  * @author bpatel
  * @library ../lib
@@ -87,7 +87,7 @@ public class TestModules extends JavadocTester {
         testModuleLink();
     }
 
-    @Test
+   @Test
     void test5() {
         javadoc("-d", "out-nomodule", "-use",
                 "-sourcepath", testSrc,
@@ -95,6 +95,18 @@ public class TestModules extends JavadocTester {
         checkExit(Exit.OK);
     }
 
+   @Test
+    void test6() {
+        javadoc("-d", "out-mdltags", "-author", "-version",
+                "-tag", "regular:a:Regular Tag:",
+                "-tag", "moduletag:s:Module Tag:",
+                "-modulesourcepath", testSrc,
+                "-addmods", "moduletags,module2",
+                "testpkgmdltags", "testpkgmdl2");
+        checkExit(Exit.OK);
+        testModuleTags();
+    }
+
     void testDescription(boolean found) {
         checkOutput("module1-summary.html", found,
                 "<!-- ============ MODULE DESCRIPTION =========== -->\n"
@@ -187,4 +199,38 @@ public class TestModules extends JavadocTester {
                 "<ul class=\"navList\" title=\"Navigation\">\n"
                 + "<li><a href=\"../../testpkgnomodule/package-summary.html\">Package</a></li>");
     }
+
+    void testModuleTags() {
+        checkOutput("moduletags-summary.html", true,
+                "Type Link: <a href=\"testpkgmdltags/TestClassInModuleTags.html\" title=\"class in "
+                + "testpkgmdltags\"><code>TestClassInModuleTags</code></a>.");
+        checkOutput("moduletags-summary.html", true,
+                "Member Link: <a href=\"testpkgmdltags/TestClassInModuleTags.html#"
+                + "testMethod-java.lang.String-\"><code>testMethod(String)</code></a>.");
+        checkOutput("moduletags-summary.html", true,
+                "Package Link: <a href=\"testpkgmdltags/package-summary.html\"><code>testpkgmdltags</code></a>.");
+        checkOutput("moduletags-summary.html", true,
+                "<dt><span class=\"simpleTagLabel\">Since:</span></dt>\n"
+                + "<dd>JDK 9</dd>");
+        checkOutput("moduletags-summary.html", true,
+                "<dt><span class=\"seeLabel\">See Also:</span></dt>\n"
+                + "<dd>\"Test see tag\", \n"
+                + "<a href=\"testpkgmdltags/TestClassInModuleTags.html\" title=\"class in testpkgmdltags\"><code>"
+                + "TestClassInModuleTags</code></a></dd>");
+        checkOutput("moduletags-summary.html", true,
+                "<dt><span class=\"simpleTagLabel\">Regular Tag:</span></dt>\n"
+                + "<dd>Just a regular simple tag.</dd>");
+        checkOutput("moduletags-summary.html", true,
+                "<dt><span class=\"simpleTagLabel\">Module Tag:</span></dt>\n"
+                + "<dd>Just a simple module tag.</dd>");
+        checkOutput("moduletags-summary.html", true,
+                "<dt><span class=\"simpleTagLabel\">Version:</span></dt>\n"
+                + "<dd>1.0</dd>");
+        checkOutput("moduletags-summary.html", true,
+                "<dt><span class=\"simpleTagLabel\">Author:</span></dt>\n"
+                + "<dd>Bhavesh Patel</dd>");
+        checkOutput("testpkgmdltags/TestClassInModuleTags.html", false,
+                "<dt><span class=\"simpleTagLabel\">Module Tag:</span></dt>\n"
+                + "<dd>Just a simple module tag.</dd>");
+    }
 }

langtools/test/jdk/javadoc/doclet/testModules/moduletags/module-info.java

@@ -0,0 +1,44 @@
+/*
+ * 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.<br>
+  * Type Link: {@link testpkgmdltags.TestClassInModuleTags}.<br>
+  * Member Link: {@link testpkgmdltags.TestClassInModuleTags#testMethod(String)}.<br>
+  * Package Link: {@link testpkgmdltags}.<br>
+  *
+  * @author Bhavesh Patel
+  * @since JDK 9
+  * @see "Test see tag"
+  * @see testpkgmdltags.TestClassInModuleTags
+  * @regular Just a regular simple tag.
+  * @moduletag Just a simple module tag.
+  * @version 1.0
+  */
+module moduletags {
+    requires module2;
+
+    exports testpkgmdltags;
+}

langtools/test/jdk/javadoc/doclet/testModules/moduletags/testpkgmdltags/TestClassInModuleTags.java

@@ -0,0 +1,35 @@
+/*
+ * 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 testpkgmdltags;
+
+/**
+ * Simple tag test
+ * @regular Just a regular simple tag.
+ * @moduletag Just a simple module tag.
+ */
+
+public class TestClassInModuleTags {
+    public void testMethod(String str){}
+}