8006248: Since addition of -Xdoclint, javadoc ignores unknown tags

Reviewed-by: jjg

src/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java

@@ -284,7 +284,7 @@ public class ConfigurationImpl extends Configuration {
         setTopFile(root);
 
         if (root instanceof RootDocImpl) {
-            ((RootDocImpl) root).initDocLint(doclintOpts);
+            ((RootDocImpl) root).initDocLint(doclintOpts, tagletManager.getCustomTagNames());
         }
     }
 

src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/TagletManager.java

@@ -205,6 +205,10 @@ public class TagletManager {
         }
     }
 
+    public Set<String> getCustomTagNames() {
+        return customTags.keySet();
+    }
+
     /**
      * Add a new <code>Taglet</code>.  Print a message to indicate whether or not
      * the Taglet was registered properly.

src/share/classes/com/sun/tools/doclint/Checker.java

@@ -71,6 +71,8 @@ import com.sun.source.doctree.SinceTree;
 import com.sun.source.doctree.StartElementTree;
 import com.sun.source.doctree.TextTree;
 import com.sun.source.doctree.ThrowsTree;
+import com.sun.source.doctree.UnknownBlockTagTree;
+import com.sun.source.doctree.UnknownInlineTagTree;
 import com.sun.source.doctree.ValueTree;
 import com.sun.source.doctree.VersionTree;
 import com.sun.source.util.DocTreePath;
@@ -841,6 +843,23 @@ public class Checker extends DocTreePathScanner<Void, Void> {
         }
     }
 
+    @Override
+    public Void visitUnknownBlockTag(UnknownBlockTagTree tree, Void ignore) {
+        checkUnknownTag(tree, tree.getTagName());
+        return super.visitUnknownBlockTag(tree, ignore);
+    }
+
+    @Override
+    public Void visitUnknownInlineTag(UnknownInlineTagTree tree, Void ignore) {
+        checkUnknownTag(tree, tree.getTagName());
+        return super.visitUnknownInlineTag(tree, ignore);
+    }
+
+    private void checkUnknownTag(DocTree tree, String tagName) {
+        if (env.customTags != null && !env.customTags.contains(tagName))
+            env.messages.error(SYNTAX, tree, "dc.tag.unknown", tagName);
+    }
+
     @Override
     public Void visitValue(ValueTree tree, Void ignore) {
         ReferenceTree ref = tree.getReference();

src/share/classes/com/sun/tools/doclint/DocLint.java

@@ -78,6 +78,8 @@ public class DocLint implements Plugin {
     public static final String XMSGS_CUSTOM_PREFIX = "-Xmsgs:";
     private static final String STATS = "-stats";
     public static final String XIMPLICIT_HEADERS = "-XimplicitHeaders:";
+    public static final String XCUSTOM_TAGS_PREFIX = "-XcustomTags:";
+    public static final String TAGS_SEPARATOR = ",";
 
     // <editor-fold defaultstate="collapsed" desc="Command-line entry point">
     public static void main(String... args) {
@@ -199,6 +201,8 @@ public class DocLint implements Plugin {
                 env.messages.setOptions(null);
             } else if (arg.startsWith(XMSGS_CUSTOM_PREFIX)) {
                 env.messages.setOptions(arg.substring(arg.indexOf(":") + 1));
+            } else if (arg.startsWith(XCUSTOM_TAGS_PREFIX)) {
+                env.setCustomTags(arg.substring(arg.indexOf(":") + 1));
             } else if (arg.equals("-h") || arg.equals("-help") || arg.equals("--help")
                     || arg.equals("-?") || arg.equals("-usage")) {
                 needHelp = true;
@@ -262,6 +266,8 @@ public class DocLint implements Plugin {
             } else if (arg.matches(XIMPLICIT_HEADERS + "[1-6]")) {
                 char ch = arg.charAt(arg.length() - 1);
                 env.setImplicitHeaders(Character.digit(ch, 10));
+            } else if (arg.startsWith(XCUSTOM_TAGS_PREFIX)) {
+                env.setCustomTags(arg.substring(arg.indexOf(":") + 1));
             } else
                 throw new IllegalArgumentException(arg);
         }

src/share/classes/com/sun/tools/doclint/Env.java

@@ -27,6 +27,7 @@ package com.sun.tools.doclint;
 
 
 import java.util.Set;
+import java.util.LinkedHashSet;
 
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ElementKind;
@@ -86,6 +87,8 @@ public class Env {
 
     int implicitHeaderLevel = 0;
 
+    Set<String> customTags;
+
     // Utility classes
     DocTrees trees;
     Elements elements;
@@ -135,6 +138,14 @@ public class Env {
         implicitHeaderLevel = n;
     }
 
+    void setCustomTags(String cTags) {
+        customTags = new LinkedHashSet<String>();
+        for (String s : cTags.split(DocLint.TAGS_SEPARATOR)) {
+            if (!s.isEmpty())
+                customTags.add(s);
+        }
+    }
+
     /** Set the current declaration and its doc comment. */
     void setCurrent(TreePath path, DocCommentTree comment) {
         currPath = path;

src/share/classes/com/sun/tools/javadoc/DocEnv.java

@@ -800,7 +800,7 @@ public class DocEnv {
         return result;
     }
 
-    void initDoclint(Collection<String> opts) {
+    void initDoclint(Collection<String> opts, Collection<String> customTagNames) {
         ArrayList<String> doclintOpts = new ArrayList<String>();
 
         for (String opt: opts) {
@@ -814,6 +814,15 @@ public class DocEnv {
             return;
         }
 
+        String sep = "";
+        StringBuilder customTags = new StringBuilder();
+        for (String customTag : customTagNames) {
+            customTags.append(sep);
+            customTags.append(customTag);
+            sep = DocLint.TAGS_SEPARATOR;
+        }
+        doclintOpts.add(DocLint.XCUSTOM_TAGS_PREFIX + customTags.toString());
+
         JavacTask t = BasicJavacTask.instance(context);
         doclint = new DocLint();
         // standard doclet normally generates H1, H2

src/share/classes/com/sun/tools/javadoc/RootDocImpl.java

@@ -377,8 +377,8 @@ public class RootDocImpl extends DocImpl implements RootDoc {
         return env.fileManager;
     }
 
-    public void initDocLint(Collection<String> opts) {
-        env.initDoclint(opts);
+    public void initDocLint(Collection<String> opts, Collection<String> customTagNames) {
+        env.initDoclint(opts, customTagNames);
     }
 
     public boolean showTagMessages() {

test/com/sun/javadoc/testCustomTag/TagTestClass.java

+/*
+ * Copyright (c) 2013, 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.
+ */
+
+/**
+ * @customTag A custom tag.
+ * @unknownTag An unknown tag
+ */
+public class TagTestClass {
+
+    public void method(){}
+}

test/com/sun/javadoc/testCustomTag/TestCustomTag.java

+/*
+ * Copyright (c) 2013, 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      8006248
+ * @summary  Test custom tag. Verify that an unknown tag generates appropriate warnings.
+ * @author   Bhavesh Patel
+ * @library  ../lib/
+ * @build    JavadocTester taglets.CustomTag TestCustomTag
+ * @run main TestCustomTag
+ */
+
+public class TestCustomTag extends JavadocTester {
+
+    //Test information.
+    private static final String BUG_ID = "8006248";
+
+    //Javadoc arguments.
+    private static final String[] ARGS = new String[] {
+        "-Xdoclint:none", "-d", BUG_ID, "-tagletpath", SRC_DIR,
+        "-taglet", "taglets.CustomTag", "-sourcepath",
+        SRC_DIR, SRC_DIR + FS + "TagTestClass.java"
+    };
+
+    private static final String[] ARGS1 = new String[] {
+        "-d", BUG_ID + "-1", "-tagletpath", SRC_DIR, "-taglet", "taglets.CustomTag",
+        "-sourcepath", SRC_DIR, SRC_DIR + FS + "TagTestClass.java"
+    };
+    private static final String[] ARGS2 = new String[] {
+        "-Xdoclint:none", "-d", BUG_ID + "-2", "-sourcepath",
+        SRC_DIR, SRC_DIR + FS + "TagTestClass.java"
+    };
+
+    private static final String[] ARGS3 = new String[] {
+        "-d", BUG_ID + "-3", "-sourcepath", SRC_DIR, SRC_DIR + FS + "TagTestClass.java"
+    };
+
+    //Input for string search tests.
+    private static final String[][] TEST = new String[][] {
+        {WARNING_OUTPUT, "warning - @unknownTag is an unknown tag."
+        }
+    };
+
+    private static final String[][] TEST1 = new String[][] {
+        {ERROR_OUTPUT, "error: unknown tag: unknownTag"
+        }
+    };
+    private static final String[][] TEST2 = new String[][] {
+        {WARNING_OUTPUT, "warning - @customTag is an unknown tag."
+        },
+        {WARNING_OUTPUT, "warning - @unknownTag is an unknown tag."
+        }
+    };
+
+    private static final String[][] TEST3 = new String[][] {
+        {ERROR_OUTPUT, "error: unknown tag: customTag"
+        },
+        {ERROR_OUTPUT, "error: unknown tag: unknownTag"
+        }
+    };
+
+    /**
+     * The entry point of the test.
+     * @param args the array of command line arguments.
+     */
+    public static void main(String[] args) {
+        TestCustomTag tester = new TestCustomTag();
+        run(tester, ARGS, TEST, NO_TEST);
+        run(tester, ARGS1, TEST1, NO_TEST);
+        run(tester, ARGS2, TEST2, NO_TEST);
+        run(tester, ARGS3, TEST3, NO_TEST);
+        tester.printSummary();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public String getBugId() {
+        return BUG_ID;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public String getBugName() {
+        return getClass().getName();
+    }
+}

test/com/sun/javadoc/testCustomTag/taglets/CustomTag.java

+/*
+ * Copyright (c) 2013, 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.
+ */
+
+package taglets;
+
+import com.sun.tools.doclets.internal.toolkit.*;
+import com.sun.tools.doclets.internal.toolkit.taglets.*;
+import com.sun.tools.doclets.internal.toolkit.util.*;
+
+import com.sun.javadoc.*;
+import java.util.*;
+
+public class CustomTag extends BaseTaglet {
+
+    public CustomTag() {
+        name = "customTag";
+    }
+
+    public static void register(Map tagletMap) {
+       CustomTag tag = new CustomTag();
+       Taglet t = (Taglet) tagletMap.get(tag.getName());
+       if (t != null) {
+           tagletMap.remove(tag.getName());
+       }
+       tagletMap.put(tag.getName(), tag);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public Content getTagletOutput(Tag tag, TagletWriter writer) {
+        ArrayList inlineTags = new ArrayList();
+        inlineTags.add(new TextTag(tag.holder(), "<dt><span class=\"simpleTagLabel\">Custom Tag:</span></dt><dd>"));
+        inlineTags.addAll(Arrays.asList(tag.inlineTags()));
+        inlineTags.add(new TextTag(tag.holder(), "</dd>"));
+        return writer.commentTagsToOutput(tag,
+                (Tag[]) inlineTags.toArray(new Tag[] {}));
+    }
+}

test/tools/doclint/CustomTagTest.java

+/*
+ * @test /nodynamiccopyright/
+ * @bug 8006248
+ * @summary DocLint should report unknown tags
+ * @build DocLintTester
+ * @run main DocLintTester CustomTagTest.java
+ * @run main DocLintTester -XcustomTags: -ref CustomTagTest.out CustomTagTest.java
+ * @run main DocLintTester -XcustomTags:customTag -ref CustomTagTestWithOption.out CustomTagTest.java
+ * @run main DocLintTester -XcustomTags:customTag,anotherCustomTag -ref CustomTagTestWithOption.out CustomTagTest.java
+ * @author bpatel
+ */
+
+/**
+ * @customTag Text for a custom tag.
+ * @unknownTag Text for an unknown tag.
+ */
+public class CustomTagTest {
+}
+

test/tools/doclint/CustomTagTest.out

+CustomTagTest.java:14: error: unknown tag: customTag
+ * @customTag Text for a custom tag.
+   ^
+CustomTagTest.java:15: error: unknown tag: unknownTag
+ * @unknownTag Text for an unknown tag.
+   ^
+2 errors
+

test/tools/doclint/CustomTagTestWithOption.out

+CustomTagTest.java:15: error: unknown tag: unknownTag
+ * @unknownTag Text for an unknown tag.
+   ^
+1 error
+

test/tools/doclint/DocLintTester.java

@@ -58,6 +58,8 @@ public class DocLintTester {
                 badArgs = true;
             } else if (arg.startsWith("-Xmsgs")) {
                 opts.add(arg);
+            } else if (arg.startsWith("-XcustomTags")) {
+                opts.add(arg);
             } else if (arg.startsWith("-")) {
                 opts.add(arg);
                 if (i < args.length - 1 && !args[i+1].startsWith("-"))