Mercurial > hg > openjdk > lambda > langtools
changeset 2584:667843bd2193
8006248: Since addition of -Xdoclint, javadoc ignores unknown tags
Reviewed-by: jjg
line wrap: on
line diff
--- a/src/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java Thu Oct 24 01:27:10 2013 -0400 +++ b/src/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java Thu Oct 24 11:22:50 2013 -0700 @@ -284,7 +284,7 @@ setTopFile(root); if (root instanceof RootDocImpl) { - ((RootDocImpl) root).initDocLint(doclintOpts); + ((RootDocImpl) root).initDocLint(doclintOpts, tagletManager.getCustomTagNames()); } }
--- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/TagletManager.java Thu Oct 24 01:27:10 2013 -0400 +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/TagletManager.java Thu Oct 24 11:22:50 2013 -0700 @@ -205,6 +205,10 @@ } } + 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.
--- a/src/share/classes/com/sun/tools/doclint/Checker.java Thu Oct 24 01:27:10 2013 -0400 +++ b/src/share/classes/com/sun/tools/doclint/Checker.java Thu Oct 24 11:22:50 2013 -0700 @@ -71,6 +71,8 @@ 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; @@ -842,6 +844,23 @@ } @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(); if (ref == null || ref.getSignature().isEmpty()) {
--- a/src/share/classes/com/sun/tools/doclint/DocLint.java Thu Oct 24 01:27:10 2013 -0400 +++ b/src/share/classes/com/sun/tools/doclint/DocLint.java Thu Oct 24 11:22:50 2013 -0700 @@ -78,6 +78,8 @@ 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 @@ 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 @@ } 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); }
--- a/src/share/classes/com/sun/tools/doclint/Env.java Thu Oct 24 01:27:10 2013 -0400 +++ b/src/share/classes/com/sun/tools/doclint/Env.java Thu Oct 24 11:22:50 2013 -0700 @@ -27,6 +27,7 @@ import java.util.Set; +import java.util.LinkedHashSet; import javax.lang.model.element.Element; import javax.lang.model.element.ElementKind; @@ -86,6 +87,8 @@ int implicitHeaderLevel = 0; + Set<String> customTags; + // Utility classes DocTrees trees; Elements elements; @@ -135,6 +138,14 @@ 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;
--- a/src/share/classes/com/sun/tools/javadoc/DocEnv.java Thu Oct 24 01:27:10 2013 -0400 +++ b/src/share/classes/com/sun/tools/javadoc/DocEnv.java Thu Oct 24 11:22:50 2013 -0700 @@ -800,7 +800,7 @@ 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 @@ 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
--- a/src/share/classes/com/sun/tools/javadoc/RootDocImpl.java Thu Oct 24 01:27:10 2013 -0400 +++ b/src/share/classes/com/sun/tools/javadoc/RootDocImpl.java Thu Oct 24 11:22:50 2013 -0700 @@ -377,8 +377,8 @@ 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() {
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/com/sun/javadoc/testCustomTag/TagTestClass.java Thu Oct 24 11:22:50 2013 -0700 @@ -0,0 +1,31 @@ +/* + * 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(){} +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/com/sun/javadoc/testCustomTag/TestCustomTag.java Thu Oct 24 11:22:50 2013 -0700 @@ -0,0 +1,109 @@ +/* + * 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(); + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/com/sun/javadoc/testCustomTag/taglets/CustomTag.java Thu Oct 24 11:22:50 2013 -0700 @@ -0,0 +1,59 @@ +/* + * 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[] {})); + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/tools/doclint/CustomTagTest.java Thu Oct 24 11:22:50 2013 -0700 @@ -0,0 +1,19 @@ +/* + * @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 { +} +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/tools/doclint/CustomTagTest.out Thu Oct 24 11:22:50 2013 -0700 @@ -0,0 +1,8 @@ +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 +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/tools/doclint/CustomTagTestWithOption.out Thu Oct 24 11:22:50 2013 -0700 @@ -0,0 +1,5 @@ +CustomTagTest.java:15: error: unknown tag: unknownTag + * @unknownTag Text for an unknown tag. + ^ +1 error +
--- a/test/tools/doclint/DocLintTester.java Thu Oct 24 01:27:10 2013 -0400 +++ b/test/tools/doclint/DocLintTester.java Thu Oct 24 11:22:50 2013 -0700 @@ -58,6 +58,8 @@ 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("-"))