changeset 53616:12956ca371c2

8213819: doclint should warn against {@index} inside <a> tag Reviewed-by: jjg, hannesw
author pmuthuswamy
date Thu, 22 Nov 2018 10:25:44 +0530
parents 148124c951fd
children e00cf18e2593
files src/jdk.compiler/share/classes/com/sun/tools/doclint/Checker.java src/jdk.compiler/share/classes/com/sun/tools/doclint/resources/doclint.properties test/langtools/jdk/javadoc/doclet/testIndexTaglet/TestIndexTaglet.java test/langtools/jdk/javadoc/doclet/testSystemPropertyTaglet/TestSystemPropertyTaglet.java
diffstat 4 files changed, 80 insertions(+), 17 deletions(-) [+]
line wrap: on
line diff
--- a/src/jdk.compiler/share/classes/com/sun/tools/doclint/Checker.java	Thu Nov 22 10:30:47 2018 +0800
+++ b/src/jdk.compiler/share/classes/com/sun/tools/doclint/Checker.java	Thu Nov 22 10:25:44 2018 +0530
@@ -59,7 +59,9 @@
 import com.sun.source.doctree.EntityTree;
 import com.sun.source.doctree.ErroneousTree;
 import com.sun.source.doctree.IdentifierTree;
+import com.sun.source.doctree.IndexTree;
 import com.sun.source.doctree.InheritDocTree;
+import com.sun.source.doctree.InlineTagTree;
 import com.sun.source.doctree.LinkTree;
 import com.sun.source.doctree.LiteralTree;
 import com.sun.source.doctree.ParamTree;
@@ -71,6 +73,7 @@
 import com.sun.source.doctree.SinceTree;
 import com.sun.source.doctree.StartElementTree;
 import com.sun.source.doctree.SummaryTree;
+import com.sun.source.doctree.SystemPropertyTree;
 import com.sun.source.doctree.TextTree;
 import com.sun.source.doctree.ThrowsTree;
 import com.sun.source.doctree.UnknownBlockTagTree;
@@ -765,6 +768,18 @@
     }
 
     @Override @DefinedBy(Api.COMPILER_TREE)
+    public Void visitIndex(IndexTree tree, Void ignore) {
+        for (TagStackItem tsi : tagStack) {
+            if (tsi.tag == HtmlTag.A) {
+                env.messages.warning(HTML, tree, "dc.tag.a.within.a",
+                        "{@" + tree.getTagName() + "}");
+                break;
+            }
+        }
+        return super.visitIndex(tree, ignore);
+    }
+
+    @Override @DefinedBy(Api.COMPILER_TREE)
     public Void visitInheritDoc(InheritDocTree tree, Void ignore) {
         markEnclosingTag(Flag.HAS_INLINE_TAG);
         // TODO: verify on overridden method
@@ -921,6 +936,18 @@
     }
 
     @Override @DefinedBy(Api.COMPILER_TREE)
+    public Void visitSystemProperty(SystemPropertyTree tree, Void ignore) {
+        for (TagStackItem tsi : tagStack) {
+            if (tsi.tag == HtmlTag.A) {
+                env.messages.warning(HTML, tree, "dc.tag.a.within.a",
+                        "{@" + tree.getTagName() + "}");
+                break;
+            }
+        }
+        return super.visitSystemProperty(tree, ignore);
+    }
+
+    @Override @DefinedBy(Api.COMPILER_TREE)
     public Void visitThrows(ThrowsTree tree, Void ignore) {
         ReferenceTree exName = tree.getExceptionName();
         Element ex = env.trees.getElement(new DocTreePath(getCurrentPath(), exName));
--- a/src/jdk.compiler/share/classes/com/sun/tools/doclint/resources/doclint.properties	Thu Nov 22 10:30:47 2018 +0800
+++ b/src/jdk.compiler/share/classes/com/sun/tools/doclint/resources/doclint.properties	Thu Nov 22 10:25:44 2018 +0530
@@ -60,6 +60,7 @@
 dc.service.not.found = service-type not found
 dc.tag.code.within.code = '{@code'} within <code>
 dc.tag.empty = empty <{0}> tag
+dc.tag.a.within.a = {0} tag, which expands to <a>, within <a>
 dc.tag.end.not.permitted = invalid end tag: </{0}>
 dc.tag.end.unexpected = unexpected end tag: </{0}>
 dc.tag.header.sequence.1 = header used out of sequence: <{0}>
--- a/test/langtools/jdk/javadoc/doclet/testIndexTaglet/TestIndexTaglet.java	Thu Nov 22 10:30:47 2018 +0800
+++ b/test/langtools/jdk/javadoc/doclet/testIndexTaglet/TestIndexTaglet.java	Thu Nov 22 10:25:44 2018 +0530
@@ -55,9 +55,17 @@
     @Test
     void test(Path base) throws Exception {
         Path srcDir = base.resolve("src");
-        createTestClass(srcDir);
+        Path outDir = base.resolve("out");
 
-        Path outDir = base.resolve("out");
+        MethodBuilder method = MethodBuilder
+                .parse("public void func(A a) {}")
+                .setComments("test description with {@index search_phrase_a class a}");
+
+        new ClassBuilder(tb, "pkg.A")
+                .setModifiers("public", "class")
+                .addMembers(method)
+                .write(srcDir);
+
         javadoc("-d", outDir.toString(),
                 "-sourcepath", srcDir.toString(),
                 "pkg");
@@ -74,15 +82,24 @@
                 "<div class=\"block\">test description with search_phrase_a</div>");
     }
 
-    void createTestClass(Path srcDir) throws Exception {
-        MethodBuilder method = MethodBuilder
-                .parse("public void func(A a) {}")
-                .setComments("test description with {@index search_phrase_a class a}");
+    @Test
+    void testIndexWithinATag(Path base) throws Exception {
+        Path srcDir = base.resolve("src");
+        Path outDir = base.resolve("out");
 
-        new ClassBuilder(tb, "pkg.A")
+        new ClassBuilder(tb, "pkg2.A")
                 .setModifiers("public", "class")
-                .addMembers(method)
+                .addMembers(MethodBuilder.parse("public void func(){}")
+                        .setComments("a within a : <a href='..'>{@index check}</a>"))
                 .write(srcDir);
 
+        javadoc("-d", outDir.toString(),
+                "-sourcepath", srcDir.toString(),
+                "pkg2");
+
+        checkExit(Exit.OK);
+
+        checkOutput(Output.OUT, true,
+                "warning: {@index} tag, which expands to <a>, within <a>");
     }
 }
--- a/test/langtools/jdk/javadoc/doclet/testSystemPropertyTaglet/TestSystemPropertyTaglet.java	Thu Nov 22 10:30:47 2018 +0800
+++ b/test/langtools/jdk/javadoc/doclet/testSystemPropertyTaglet/TestSystemPropertyTaglet.java	Thu Nov 22 10:25:44 2018 +0530
@@ -55,9 +55,18 @@
     @Test
     void test(Path base) throws Exception {
         Path srcDir = base.resolve("src");
-        createTestClass(srcDir);
+        Path outDir = base.resolve("out");
 
-        Path outDir = base.resolve("out");
+        MethodBuilder method = MethodBuilder
+                .parse("public void func(A a) {}")
+                .setComments("test with {@systemProperty java.version}");
+
+        new ClassBuilder(tb, "pkg.A")
+                .setComments("test with {@systemProperty user.name}")
+                .setModifiers("public", "class")
+                .addMembers(method)
+                .write(srcDir);
+
         javadoc("-d", outDir.toString(),
                 "-sourcepath", srcDir.toString(),
                 "pkg");
@@ -87,15 +96,24 @@
                 + "\"u\":\"pkg/A.html#user.name\"}");
     }
 
-    void createTestClass(Path srcDir) throws Exception {
-        MethodBuilder method = MethodBuilder
-                .parse("public void func(A a) {}")
-                .setComments("test with {@systemProperty java.version}");
+    @Test
+    void testSystemProperytWithinATag(Path base) throws Exception {
+        Path srcDir = base.resolve("src");
+        Path outDir = base.resolve("out");
 
-        new ClassBuilder(tb, "pkg.A")
-                .setComments("test with {@systemProperty user.name}")
+        new ClassBuilder(tb, "pkg2.A")
                 .setModifiers("public", "class")
-                .addMembers(method)
+                .addMembers(MethodBuilder.parse("public void func(){}")
+                        .setComments("a within a : <a href='..'>{@systemProperty user.name}</a>"))
                 .write(srcDir);
+
+        javadoc("-d", outDir.toString(),
+                "-sourcepath", srcDir.toString(),
+                "pkg2");
+
+        checkExit(Exit.OK);
+
+        checkOutput(Output.OUT, true,
+                "warning: {@systemProperty} tag, which expands to <a>, within <a>");
     }
 }