Skip to content
Permalink
Browse files
8246712: doclint incorrectly reports some HTML elements as empty
Reviewed-by: prappo
  • Loading branch information
jonathan-gibbons committed Jun 10, 2020
1 parent 80ae89b commit 56abdc178eb4f7d56865d0c1b71272d2835b071c
Showing 2 changed files with 155 additions and 0 deletions.
@@ -803,6 +803,7 @@ public Void visitDocRoot(DocRootTree tree, Void ignore) {

@Override @DefinedBy(Api.COMPILER_TREE)
public Void visitIndex(IndexTree tree, Void ignore) {
markEnclosingTag(Flag.HAS_INLINE_TAG);
for (TagStackItem tsi : tagStack) {
if (tsi.tag == HtmlTag.A) {
env.messages.warning(HTML, tree, "dc.tag.a.within.a",
@@ -956,6 +957,7 @@ public Void visitSince(SinceTree tree, Void ignore) {

@Override @DefinedBy(Api.COMPILER_TREE)
public Void visitSummary(SummaryTree node, Void aVoid) {
markEnclosingTag(Flag.HAS_INLINE_TAG);
int idx = env.currDocComment.getFullBody().indexOf(node);
// Warn if the node is preceded by non-whitespace characters,
// or other non-text nodes.
@@ -967,6 +969,7 @@ public Void visitSummary(SummaryTree node, Void aVoid) {

@Override @DefinedBy(Api.COMPILER_TREE)
public Void visitSystemProperty(SystemPropertyTree tree, Void ignore) {
markEnclosingTag(Flag.HAS_INLINE_TAG);
for (TagStackItem tsi : tagStack) {
if (tsi.tag == HtmlTag.A) {
env.messages.warning(HTML, tree, "dc.tag.a.within.a",
@@ -1041,6 +1044,7 @@ public Void visitUnknownBlockTag(UnknownBlockTagTree tree, Void ignore) {

@Override @DefinedBy(Api.COMPILER_TREE)
public Void visitUnknownInlineTag(UnknownInlineTagTree tree, Void ignore) {
markEnclosingTag(Flag.HAS_INLINE_TAG);
checkUnknownTag(tree, tree.getTagName());
return super.visitUnknownInlineTag(tree, ignore);
}
@@ -0,0 +1,151 @@
/*
* Copyright (c) 2020, 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 8246712
* @summary doclint incorrectly reports some HTML elements as empty
* @modules jdk.compiler/com.sun.tools.doclint
* @library /tools/lib
* @build toolbox.TestRunner toolbox.ToolBox
* @run main EmptyHtmlTest
*/

import java.io.PrintWriter;
import java.io.StringWriter;
import java.lang.reflect.Method;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

import com.sun.source.doctree.DocTreeVisitor;
import com.sun.source.doctree.InlineTagTree;
import com.sun.tools.doclint.DocLint;
import toolbox.TestRunner;
import toolbox.ToolBox;

public class EmptyHtmlTest extends TestRunner {

public static void main(String... args) throws Exception {
EmptyHtmlTest t = new EmptyHtmlTest();
t.runTests(m -> new Object[] { Path.of(m.getName()) });
}

public EmptyHtmlTest() {
super(System.err);
}

ToolBox tb = new ToolBox();

/**
* This test is intended to be future-proof, and hence detect any
* problems in any inline tags added in the future.
* Since there is not yet any mapping between DocTree.Kind and
* the corresponding subtype DocTree (see javac Tree.Kind, Tree)
* the list of all current inline tag classes is determined by
* scanning DocTreeVisitor.
*
* @param base working directory for the test case
* @throws Exception if an error occurs
*/
@Test
public void testInlines(Path base) throws Exception {
Class<DocTreeVisitor> c = DocTreeVisitor.class;
for (Method m : c.getDeclaredMethods()) {
if (m.getName().startsWith("visit") && m.getParameterCount() == 2) {
Class<?>[] paramTypes = m.getParameterTypes();
Class<?> firstParamType = paramTypes[0];
if (InlineTagTree.class.isAssignableFrom(firstParamType)) {
testInline(base, firstParamType);
}
}
}
}

void testInline(Path base, Class<?> type) throws Exception {
// the following can eventually be converted to instanceof pattern switch
Path d = Files.createDirectories(base.resolve(type.getSimpleName()));
switch (type.getSimpleName()) {
case "DocRootTree" ->
test(d, type, "{@docRoot}");

case "IndexTree" ->
test(d, type, "{@index Object}");

case "InheritDocTree" ->
test(d, type, "{@inheritDoc}");

case "LinkTree" ->
test(d, type, "{@link Object}");

case "LiteralTree" ->
test(d, type, "{@literal abc}");

case "SummaryTree" ->
test(d, type, "{@summary First sentence.}");

case "SystemPropertyTree" ->
test(d, type, "{@systemProperty file.separator}");

case "UnknownInlineTagTree" ->
test(d, type, "{@unknown}");

case "ValueTree" ->
test(d, type, "{@value Math.PI}");

default ->
error("no test case provided for " + type);
}
}

void test(Path base, Class<?> type, String tag) throws Exception {
System.err.println("test " + type.getSimpleName() + " " + tag);
Path src = base.resolve("src");
String text = """
/**
* This is a comment.
* <b>INSERT</b>
*/
public class C { }
""".replace("INSERT", tag);
tb.writeJavaFiles(src, text);

List<String> cmdArgs = List.of(
"-Xmsgs:html",
"-XcustomTags:unknown",
src.resolve("C.java").toString()
);

StringWriter sw = new StringWriter();
try (PrintWriter pw = new PrintWriter(sw)) {
new DocLint().run(pw, cmdArgs.toArray(new String[0]));
}
String log = sw.toString();
if (!log.isEmpty()) {
System.err.println("output:");
log.lines().forEach(System.err::println);
error("Unexpected output from doclint");
}
}
}

0 comments on commit 56abdc1

Please sign in to comment.