8273544: Increase test coverage for snippets
Reviewed-by: jjg
This commit is contained in:
Pavel Rappo
parent
2d4af2255f
commit
2ab43ec242
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets
formats/html
toolkit
test/langtools/jdk/javadoc/doclet/testSnippetTag
@ -429,7 +429,7 @@ public class TagletWriterImpl extends TagletWriter {
|
||||
String strippedLine = line.strip();
|
||||
int idx = line.indexOf(strippedLine);
|
||||
assert idx >= 0; // because the stripped line is a substring of the line being stripped
|
||||
Text whitespace = Text.of(line.substring(0, idx));
|
||||
Text whitespace = Text.of(utils.normalizeNewlines(line.substring(0, idx)));
|
||||
// If the leading whitespace is not excluded from the link,
|
||||
// browsers might exhibit unwanted behavior. For example, a
|
||||
// browser might display hand-click cursor while user hovers
|
||||
@ -438,7 +438,7 @@ public class TagletWriterImpl extends TagletWriter {
|
||||
c = new ContentBuilder(whitespace, htmlWriter.linkToContent(element, e, t, strippedLine));
|
||||
// We don't care about trailing whitespace.
|
||||
} else {
|
||||
c = HtmlTree.SPAN(Text.of(sequence));
|
||||
c = HtmlTree.SPAN(Text.of(utils.normalizeNewlines(sequence)));
|
||||
classes.forEach(((HtmlTree) c)::addStyle);
|
||||
}
|
||||
code.add(c);
|
||||
|
||||
@ -361,6 +361,9 @@ doclet.snippet.region.not_found=\
|
||||
doclet.tag.attribute.value.illegal=\
|
||||
illegal value for attribute "{0}": "{1}"
|
||||
|
||||
doclet.tag.attribute.value.missing=\
|
||||
missing value for attribute "{0}"
|
||||
|
||||
doclet.tag.attribute.repeated=\
|
||||
repeated attribute: "{0}"
|
||||
|
||||
|
||||
@ -28,7 +28,6 @@ package jdk.javadoc.internal.doclets.toolkit.taglets;
|
||||
import java.io.IOException;
|
||||
import java.util.EnumSet;
|
||||
import java.util.HashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
import java.util.stream.Collectors;
|
||||
@ -84,6 +83,45 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
*/
|
||||
@Override
|
||||
public Content getInlineTagOutput(Element holder, DocTree tag, TagletWriter writer) {
|
||||
try {
|
||||
return generateContent(holder, tag, writer);
|
||||
} catch (BadSnippetException e) {
|
||||
error(writer, holder, e.tag(), e.key(), e.args());
|
||||
return badSnippet(writer);
|
||||
}
|
||||
}
|
||||
|
||||
private static final class BadSnippetException extends Exception {
|
||||
|
||||
@java.io.Serial
|
||||
private static final long serialVersionUID = 1;
|
||||
|
||||
private final transient DocTree tag;
|
||||
private final String key;
|
||||
private final transient Object[] args;
|
||||
|
||||
BadSnippetException(DocTree tag, String key, Object... args) {
|
||||
this.tag = tag;
|
||||
this.key = key;
|
||||
this.args = args;
|
||||
}
|
||||
|
||||
DocTree tag() {
|
||||
return tag;
|
||||
}
|
||||
|
||||
String key() {
|
||||
return key;
|
||||
}
|
||||
|
||||
Object[] args() {
|
||||
return args;
|
||||
}
|
||||
}
|
||||
|
||||
private Content generateContent(Element holder, DocTree tag, TagletWriter writer)
|
||||
throws BadSnippetException
|
||||
{
|
||||
SnippetTree snippetTag = (SnippetTree) tag;
|
||||
|
||||
// organize snippet attributes in a map, performing basic checks along the way
|
||||
@ -98,9 +136,8 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
// two like-named attributes found; although we report on the most
|
||||
// recently encountered of the two, the iteration order might differ
|
||||
// from the source order (see JDK-8266826)
|
||||
error(writer, holder, a, "doclet.tag.attribute.repeated",
|
||||
a.getName().toString());
|
||||
return badSnippet(writer);
|
||||
throw new BadSnippetException(a, "doclet.tag.attribute.repeated",
|
||||
a.getName().toString());
|
||||
}
|
||||
|
||||
final String CLASS = "class";
|
||||
@ -111,22 +148,19 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
final boolean containsBody = snippetTag.getBody() != null;
|
||||
|
||||
if (containsClass && containsFile) {
|
||||
error(writer, holder, attributes.get(CLASS),
|
||||
"doclet.snippet.contents.ambiguity.external");
|
||||
return badSnippet(writer);
|
||||
throw new BadSnippetException(attributes.get(CLASS),
|
||||
"doclet.snippet.contents.ambiguity.external");
|
||||
} else if (!containsClass && !containsFile && !containsBody) {
|
||||
error(writer, holder, tag, "doclet.snippet.contents.none");
|
||||
return badSnippet(writer);
|
||||
throw new BadSnippetException(tag, "doclet.snippet.contents.none");
|
||||
}
|
||||
|
||||
String regionName = null;
|
||||
AttributeTree region = attributes.get("region");
|
||||
if (region != null) {
|
||||
regionName = stringOf(region.getValue());
|
||||
regionName = stringValueOf(region);
|
||||
if (regionName.isBlank()) {
|
||||
error(writer, holder, region, "doclet.tag.attribute.value.illegal",
|
||||
"region", region.getValue());
|
||||
return badSnippet(writer);
|
||||
throw new BadSnippetException(region, "doclet.tag.attribute.value.illegal",
|
||||
"region", region.getValue());
|
||||
}
|
||||
}
|
||||
|
||||
@ -141,12 +175,12 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
if (containsFile || containsClass) {
|
||||
AttributeTree a;
|
||||
String v = containsFile
|
||||
? stringOf((a = attributes.get(FILE)).getValue())
|
||||
: stringOf((a = attributes.get(CLASS)).getValue()).replace(".", "/") + ".java";
|
||||
? stringValueOf((a = attributes.get(FILE)))
|
||||
: stringValueOf((a = attributes.get(CLASS))).replace(".", "/") + ".java";
|
||||
|
||||
if (v.isBlank()) {
|
||||
error(writer, holder, a, "doclet.tag.attribute.value.illegal",
|
||||
containsFile ? FILE : CLASS, v);
|
||||
throw new BadSnippetException(a, "doclet.tag.attribute.value.illegal",
|
||||
containsFile ? FILE : CLASS, v);
|
||||
}
|
||||
|
||||
// we didn't create JavaFileManager, so we won't close it; even if an error occurs
|
||||
@ -165,24 +199,21 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
if (fileObject == null && fileManager.hasLocation(Location.SNIPPET_PATH)) {
|
||||
fileObject = fileManager.getFileForInput(Location.SNIPPET_PATH, "", v);
|
||||
}
|
||||
} catch (IOException | IllegalArgumentException e) {
|
||||
} catch (IOException | IllegalArgumentException e) { // TODO: test this when JDK-8276892 is integrated
|
||||
// JavaFileManager.getFileForInput can throw IllegalArgumentException in certain cases
|
||||
error(writer, holder, a, "doclet.exception.read.file", v, e.getCause());
|
||||
return badSnippet(writer);
|
||||
throw new BadSnippetException(a, "doclet.exception.read.file", v, e.getCause());
|
||||
}
|
||||
|
||||
if (fileObject == null) {
|
||||
// i.e. the file does not exist
|
||||
error(writer, holder, a, "doclet.File_not_found", v);
|
||||
return badSnippet(writer);
|
||||
throw new BadSnippetException(a, "doclet.File_not_found", v);
|
||||
}
|
||||
|
||||
try {
|
||||
externalContent = fileObject.getCharContent(true).toString();
|
||||
} catch (IOException e) {
|
||||
error(writer, holder, a, "doclet.exception.read.file",
|
||||
fileObject.getName(), e.getCause());
|
||||
return badSnippet(writer);
|
||||
} catch (IOException e) { // TODO: test this when JDK-8276892 is integrated
|
||||
throw new BadSnippetException(a, "doclet.exception.read.file",
|
||||
fileObject.getName(), e.getCause());
|
||||
}
|
||||
}
|
||||
|
||||
@ -197,12 +228,12 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
}
|
||||
} catch (ParseException e) {
|
||||
var path = writer.configuration().utils.getCommentHelper(holder)
|
||||
.getDocTreePath(snippetTag.getBody());
|
||||
.getDocTreePath(snippetTag.getBody());
|
||||
// TODO: there should be a method in Messages; that method should mirror Reporter's; use that method instead accessing Reporter.
|
||||
String msg = writer.configuration().getDocResources()
|
||||
.getText("doclet.snippet.markup", e.getMessage());
|
||||
.getText("doclet.snippet.markup", e.getMessage());
|
||||
writer.configuration().getReporter().print(Diagnostic.Kind.ERROR,
|
||||
path, e.getPosition(), e.getPosition(), e.getPosition(), msg);
|
||||
path, e.getPosition(), e.getPosition(), e.getPosition(), msg);
|
||||
return badSnippet(writer);
|
||||
}
|
||||
|
||||
@ -213,7 +244,7 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
} catch (ParseException e) {
|
||||
assert fileObject != null;
|
||||
writer.configuration().getMessages().error(fileObject, e.getPosition(),
|
||||
e.getPosition(), e.getPosition(), "doclet.snippet.markup", e.getMessage());
|
||||
e.getPosition(), e.getPosition(), "doclet.snippet.markup", e.getMessage());
|
||||
return badSnippet(writer);
|
||||
}
|
||||
|
||||
@ -235,8 +266,7 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
}
|
||||
}
|
||||
if (r1 == null && r2 == null) {
|
||||
error(writer, holder, tag, "doclet.snippet.region.not_found", regionName);
|
||||
return badSnippet(writer);
|
||||
throw new BadSnippetException(tag, "doclet.snippet.region.not_found", regionName);
|
||||
}
|
||||
}
|
||||
|
||||
@ -252,9 +282,7 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
String inlineStr = inlineSnippet.asCharSequence().toString();
|
||||
String externalStr = externalSnippet.asCharSequence().toString();
|
||||
if (!Objects.equals(inlineStr, externalStr)) {
|
||||
error(writer, holder, tag, "doclet.snippet.contents.mismatch", diff(inlineStr, externalStr));
|
||||
// output one above the other
|
||||
return badSnippet(writer);
|
||||
throw new BadSnippetException(tag, "doclet.snippet.contents.mismatch", diff(inlineStr, externalStr));
|
||||
}
|
||||
}
|
||||
|
||||
@ -263,17 +291,17 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
|
||||
String lang = null;
|
||||
AttributeTree langAttr = attributes.get("lang");
|
||||
if (langAttr != null && langAttr.getValueKind() != AttributeTree.ValueKind.EMPTY) {
|
||||
lang = stringOf(langAttr.getValue());
|
||||
if (langAttr != null) {
|
||||
lang = stringValueOf(langAttr);
|
||||
} else if (containsClass) {
|
||||
lang = "java";
|
||||
} else if (containsFile) {
|
||||
lang = languageFromFileName(fileObject.getName());
|
||||
}
|
||||
AttributeTree idAttr = attributes.get("id");
|
||||
String id = idAttr == null || idAttr.getValueKind() == AttributeTree.ValueKind.EMPTY
|
||||
? null
|
||||
: stringOf(idAttr.getValue());
|
||||
String id = idAttr == null
|
||||
? null
|
||||
: stringValueOf(idAttr);
|
||||
|
||||
return writer.snippetTagOutput(holder, snippetTag, text, id, lang);
|
||||
}
|
||||
@ -304,8 +332,12 @@ public class SnippetTaglet extends BaseTaglet {
|
||||
return result.text();
|
||||
}
|
||||
|
||||
private static String stringOf(List<? extends DocTree> value) {
|
||||
return value.stream()
|
||||
private static String stringValueOf(AttributeTree at) throws BadSnippetException {
|
||||
if (at.getValueKind() == AttributeTree.ValueKind.EMPTY) {
|
||||
throw new BadSnippetException(at, "doclet.tag.attribute.value.missing",
|
||||
at.getName().toString());
|
||||
}
|
||||
return at.getValue().stream()
|
||||
// value consists of TextTree or ErroneousTree nodes;
|
||||
// ErroneousTree is a subtype of TextTree
|
||||
.map(t -> ((TextTree) t).getBody())
|
||||
|
||||
@ -58,8 +58,7 @@ import java.util.Objects;
|
||||
* This code and its internal interfaces are subject to change or
|
||||
* deletion without notice.</b>
|
||||
*/
|
||||
// TODO: uncomment /* sealed */ when minimum boot JDK version >= 17
|
||||
public /* sealed */ abstract class Attribute {
|
||||
public abstract class Attribute {
|
||||
|
||||
private final String name;
|
||||
|
||||
|
||||
8
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Attributes.java
8
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Attributes.java
@ -67,12 +67,4 @@ public final class Attributes {
|
||||
.map(type::cast)
|
||||
.findAny();
|
||||
}
|
||||
|
||||
public int size() {
|
||||
return attributes.values().stream().mapToInt(List::size).sum();
|
||||
}
|
||||
|
||||
public boolean isEmpty() {
|
||||
return attributes.isEmpty();
|
||||
}
|
||||
}
|
||||
|
||||
@ -152,15 +152,15 @@ public final class Parser {
|
||||
line = rawLine + (addLineTerminator ? "\n" : "");
|
||||
} else {
|
||||
String maybeMarkup = markedUpLine.group(3);
|
||||
List<Tag> parsedTags = null;
|
||||
List<Tag> parsedTags;
|
||||
try {
|
||||
parsedTags = markupParser.parse(maybeMarkup);
|
||||
} catch (ParseException e) {
|
||||
// adjust index
|
||||
// translate error position from markup to file line
|
||||
throw new ParseException(e::getMessage, markedUpLine.start(3) + e.getPosition());
|
||||
}
|
||||
for (Tag t : parsedTags) {
|
||||
t.lineSourceOffset = next.offset;
|
||||
t.lineSourceOffset = next.offset();
|
||||
t.markupLineOffset = markedUpLine.start(3);
|
||||
}
|
||||
thisLineTags.addAll(parsedTags);
|
||||
|
||||
@ -66,7 +66,7 @@ public final class Replace implements Action {
|
||||
Matcher matcher = pattern.matcher(textString);
|
||||
var replacements = new ArrayList<Replacement>();
|
||||
StringBuilder b = new StringBuilder();
|
||||
int off = 0; // offset because of the replacements (can be negative)
|
||||
int off = 0; // cumulative offset caused by replacements (can become negative)
|
||||
while (matcher.find()) {
|
||||
int start = matcher.start();
|
||||
int end = matcher.end();
|
||||
@ -79,7 +79,7 @@ public final class Replace implements Action {
|
||||
// there's no need to call matcher.appendTail(b)
|
||||
for (int i = replacements.size() - 1; i >= 0; i--) {
|
||||
Replacement r = replacements.get(i);
|
||||
text.subText(r.start, r.end).replace(Set.of(), r.value);
|
||||
text.subText(r.start(), r.end()).replace(Set.of(), r.value());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -33,8 +33,7 @@ package jdk.javadoc.internal.doclets.toolkit.taglets.snippet;
|
||||
* This code and its internal interfaces are subject to change or
|
||||
* deletion without notice.</b>
|
||||
*/
|
||||
// TODO: uncomment /* sealed */ when minimum boot JDK version >= 17
|
||||
public /* sealed */ interface Style {
|
||||
public sealed interface Style {
|
||||
|
||||
/**
|
||||
* A style that describes a link. Characters of this style are typically
|
||||
|
||||
@ -0,0 +1,119 @@
|
||||
/*
|
||||
* Copyright (c) 2021, 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.
|
||||
*/
|
||||
|
||||
import java.io.IOException;
|
||||
import java.io.UncheckedIOException;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.nio.file.StandardOpenOption;
|
||||
import java.util.Arrays;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import java.util.function.ObjIntConsumer;
|
||||
import java.util.regex.Matcher;
|
||||
import java.util.regex.Pattern;
|
||||
import java.util.stream.Stream;
|
||||
|
||||
import javadoc.tester.JavadocTester;
|
||||
import toolbox.ToolBox;
|
||||
|
||||
public class SnippetTester extends JavadocTester {
|
||||
|
||||
protected final ToolBox tb = new ToolBox();
|
||||
|
||||
protected void checkOrder(Output output, String... strings) {
|
||||
new OutputChecker(output).setExpectOrdered(true).check(strings);
|
||||
}
|
||||
|
||||
/*
|
||||
* When checking for errors, it is important not to confuse one error with
|
||||
* another. This method checks that there are no crashes (which are also
|
||||
* errors) by checking for stack traces. We never expect crashes.
|
||||
*/
|
||||
protected void checkNoCrashes() {
|
||||
checking("check crashes");
|
||||
Matcher matcher = Pattern.compile("\\s*at.*\\(.*\\.java:\\d+\\)")
|
||||
.matcher(getOutput(Output.STDERR));
|
||||
if (!matcher.find()) {
|
||||
passed("");
|
||||
} else {
|
||||
failed("Looks like a stacktrace: " + matcher.group());
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* This is a convenience method to iterate through a list.
|
||||
* Unlike List.forEach, this method provides the consumer not only with an
|
||||
* element but also that element's index.
|
||||
*
|
||||
* See JDK-8184707.
|
||||
*/
|
||||
protected static <T> void forEachNumbered(List<T> list, ObjIntConsumer<? super T> action) {
|
||||
for (var iterator = list.listIterator(); iterator.hasNext(); ) {
|
||||
action.accept(iterator.next(), iterator.previousIndex());
|
||||
}
|
||||
}
|
||||
|
||||
// TODO:
|
||||
// Explore the toolbox.ToolBox.writeFile and toolbox.ToolBox.writeJavaFiles methods:
|
||||
// see if any of them could be used instead of this one
|
||||
protected static void addSnippetFile(Path srcDir, String packageName, String fileName, String content)
|
||||
throws UncheckedIOException
|
||||
{
|
||||
String[] components = packageName.split("\\.");
|
||||
Path snippetFiles = Path.of(components[0], Arrays.copyOfRange(components, 1, components.length)).resolve("snippet-files");
|
||||
try {
|
||||
Path p = Files.createDirectories(srcDir.resolve(snippetFiles));
|
||||
Files.writeString(p.resolve(fileName), content, StandardOpenOption.CREATE_NEW);
|
||||
} catch (IOException e) {
|
||||
throw new UncheckedIOException(e);
|
||||
}
|
||||
}
|
||||
|
||||
protected void checkOutputEither(Output out, String first, String... other) {
|
||||
var strings = Stream.concat(Stream.of(first), Stream.of(other))
|
||||
.toArray(String[]::new);
|
||||
new OutputChecker(out).checkAnyOf(strings);
|
||||
}
|
||||
|
||||
protected String getSnippetHtmlRepresentation(String pathToHtmlFile,
|
||||
String content) {
|
||||
return getSnippetHtmlRepresentation(pathToHtmlFile, content, Optional.empty(), Optional.empty());
|
||||
}
|
||||
|
||||
protected String getSnippetHtmlRepresentation(String pathToHtmlFile,
|
||||
String content,
|
||||
Optional<String> lang,
|
||||
Optional<String> id) {
|
||||
// the further away from the root, the further to reach to common resources
|
||||
int nComponents = (int) pathToHtmlFile.chars().filter(c -> c == '/').count();
|
||||
var svgString = "../".repeat(nComponents) + "copy.svg";
|
||||
var idString = id.isEmpty() ? "" : " id=\"%s\"".formatted(id.get());
|
||||
var langString = lang.isEmpty() ? "" : " class=\"language-%s\"".formatted(lang.get());
|
||||
return """
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySnippet(this)">\
|
||||
<span data-copied="Copied!">Copy</span><img src="%s" alt="Copy"></button>
|
||||
<pre class="snippet"%s><code%s>%s</code></pre>
|
||||
</div>""".formatted(svgString, idString, langString, content);
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,574 @@
|
||||
/*
|
||||
* Copyright (c) 2021, 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 8266666
|
||||
* @summary Implementation for snippets
|
||||
* @library /tools/lib ../../lib
|
||||
* @modules jdk.compiler/com.sun.tools.javac.api
|
||||
* jdk.compiler/com.sun.tools.javac.main
|
||||
* jdk.javadoc/jdk.javadoc.internal.tool
|
||||
* @build javadoc.tester.* toolbox.ToolBox toolbox.ModuleBuilder builder.ClassBuilder
|
||||
* @run main TestSnippetMarkup
|
||||
*/
|
||||
|
||||
import java.io.ByteArrayInputStream;
|
||||
import java.io.File;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.io.OutputStream;
|
||||
import java.io.Reader;
|
||||
import java.io.StringReader;
|
||||
import java.io.StringWriter;
|
||||
import java.io.UncheckedIOException;
|
||||
import java.io.Writer;
|
||||
import java.net.URI;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.nio.file.Paths;
|
||||
import java.util.ArrayList;
|
||||
import java.util.Collection;
|
||||
import java.util.Collections;
|
||||
import java.util.List;
|
||||
import java.util.concurrent.atomic.AtomicLong;
|
||||
import java.util.function.Function;
|
||||
import java.util.regex.MatchResult;
|
||||
import java.util.regex.Matcher;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
import javax.lang.model.element.Modifier;
|
||||
import javax.lang.model.element.NestingKind;
|
||||
import javax.tools.FileObject;
|
||||
import javax.tools.JavaFileObject;
|
||||
import javax.tools.StandardJavaFileManager;
|
||||
import javax.tools.ToolProvider;
|
||||
|
||||
import builder.ClassBuilder;
|
||||
import toolbox.ToolBox;
|
||||
|
||||
import static javax.tools.DocumentationTool.Location.DOCUMENTATION_OUTPUT;
|
||||
|
||||
public class TestSnippetMarkup extends SnippetTester {
|
||||
|
||||
public static void main(String... args) throws Exception {
|
||||
new TestSnippetMarkup().runTests(m -> new Object[]{Paths.get(m.getName())});
|
||||
}
|
||||
|
||||
/*
|
||||
* The semantics of expectedOutput depends on the test case this record is
|
||||
* used in.
|
||||
*/
|
||||
record TestCase(String region, String input, String expectedOutput) {
|
||||
TestCase(String input, String expectedOutput) {
|
||||
this("", input, expectedOutput);
|
||||
}
|
||||
}
|
||||
|
||||
// @highlight [region|region=<name>]
|
||||
// [regex=<val>|substring=<val>]
|
||||
// [type=bold|italics|highlighted]
|
||||
// [:]
|
||||
@Test
|
||||
public void testHighlight(Path base) throws Exception {
|
||||
var testCases = List.of(
|
||||
new TestCase( // FIXME: newline should not be included
|
||||
"""
|
||||
First line // @highlight
|
||||
Second line
|
||||
""",
|
||||
"""
|
||||
<span class="bold">First line
|
||||
</span> Second line
|
||||
"""),
|
||||
new TestCase(
|
||||
"""
|
||||
First line // @highlight regex="\\w" type="bold"
|
||||
Second line
|
||||
""",
|
||||
"""
|
||||
<span class="bold">First</span> <span class="bold">line</span>
|
||||
Second line
|
||||
"""),
|
||||
new TestCase( // FIXME: newline should not be included
|
||||
"""
|
||||
First line // @highlight @highlight regex="\\w" type="bold"
|
||||
Second line
|
||||
""",
|
||||
"""
|
||||
<span class="bold">First line
|
||||
</span> Second line
|
||||
"""
|
||||
));
|
||||
testPositive(base, testCases);
|
||||
}
|
||||
|
||||
// @replace [region|region=<name>]
|
||||
// [regex=<val>|substring=<val>]
|
||||
// [replacement=<val>]
|
||||
// [:]
|
||||
@Test
|
||||
public void testReplace(Path base) throws Exception {
|
||||
var testCases = List.of(
|
||||
new TestCase(
|
||||
"""
|
||||
First line // @replace regex="\\w" replacement="."
|
||||
Second line
|
||||
""",
|
||||
"""
|
||||
..... ....
|
||||
Second line
|
||||
"""),
|
||||
new TestCase( // "substring" is not treated like "regex"
|
||||
"""
|
||||
First line // @replace substring="\\w" replacement="."
|
||||
Second line
|
||||
""",
|
||||
"""
|
||||
First line
|
||||
Second line
|
||||
"""
|
||||
),
|
||||
new TestCase(
|
||||
"""
|
||||
First line // @replace substring="i" replacement="."
|
||||
Second line
|
||||
""",
|
||||
"""
|
||||
F.rst l.ne
|
||||
Second line
|
||||
"""
|
||||
));
|
||||
testPositive(base, testCases);
|
||||
}
|
||||
|
||||
// @link [region|region=<name>]
|
||||
// [regex=<val>|substring=<val>]
|
||||
// [target=<val>]
|
||||
// [type=link|linkplain]
|
||||
// [:]
|
||||
@Test
|
||||
public void testLink(Path base) throws Exception {
|
||||
var testCases = List.of(
|
||||
new TestCase(
|
||||
"""
|
||||
First line // @link regex="\\w" target="java.lang.Object#Object"
|
||||
Second line
|
||||
""",
|
||||
replace("""
|
||||
link(First) link(line)
|
||||
Second line
|
||||
""", "link\\((.+?)\\)", r -> link(true, "java.lang.Object#Object", r.group(1)))
|
||||
));
|
||||
testPositive(base, testCases);
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testCornerCases(Path base) throws Exception {
|
||||
var testCases = List.of(
|
||||
new TestCase( // This is how one might represent a unicode escape sequence uninterpreted, if required.
|
||||
"""
|
||||
\\$0041 // @replace substring="$" replacement="u"
|
||||
""",
|
||||
"""
|
||||
\\u0041
|
||||
"""
|
||||
),
|
||||
new TestCase( // This is how one might represent `*/` without ending an enclosing comment, if required.
|
||||
// A non-whitespace character that is also not `*` is needed before `*` so that `*`
|
||||
// is not confused with the optional doc comment decoration.
|
||||
// (We cannot use, for example, `**$` or ` *$`.)
|
||||
"""
|
||||
a*$ // @replace substring="$" replacement="/"
|
||||
""",
|
||||
"""
|
||||
a*/
|
||||
"""
|
||||
),
|
||||
new TestCase( // This is how one might output markup, if required.
|
||||
// Append a no-op markup since only the rightmost markup is parsed.
|
||||
"""
|
||||
// @highlight // @start region=throwaway @end
|
||||
""",
|
||||
"""
|
||||
// @highlight
|
||||
"""
|
||||
)
|
||||
);
|
||||
testPositive(base, testCases);
|
||||
}
|
||||
|
||||
/*
|
||||
* For all but the last line of snippet source, next-line markup behaves
|
||||
* as if that markup without the next-line modifier were put on that
|
||||
* next line.
|
||||
*/
|
||||
// @Test
|
||||
public void testPositiveInlineExternalTagMarkup_NextLine(Path base) throws Exception {
|
||||
throw new RuntimeException("Not yet implemented");
|
||||
}
|
||||
|
||||
/*
|
||||
* If next-line markup is put on the last line of a snippet source,
|
||||
* an error occurs.
|
||||
*/
|
||||
@Test
|
||||
public void testNegativeInlineExternalHybridTagMarkup_NextLinePutOnLastLine(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var goodFile = "good.txt";
|
||||
var badFile = "bad.txt";
|
||||
var badFile2 = "bad2.txt"; // to workaround error deduplication
|
||||
new ClassBuilder(tb, "pkg.A")
|
||||
.setModifiers("public", "class")
|
||||
.addMembers(
|
||||
ClassBuilder.MethodBuilder
|
||||
.parse("public void inline() { }")
|
||||
.setComments("""
|
||||
{@snippet :
|
||||
First line // @highlight :
|
||||
}
|
||||
"""))
|
||||
.addMembers(
|
||||
ClassBuilder.MethodBuilder
|
||||
.parse("public void external() { }")
|
||||
.setComments("""
|
||||
{@snippet file="%s"}
|
||||
""".formatted(badFile)))
|
||||
.addMembers(
|
||||
ClassBuilder.MethodBuilder
|
||||
.parse("public void hybrid1() { }")
|
||||
.setComments("""
|
||||
{@snippet file="%s":
|
||||
First line
|
||||
}
|
||||
""".formatted(badFile2)))
|
||||
.addMembers(
|
||||
ClassBuilder.MethodBuilder
|
||||
.parse("public void hybrid2() { }")
|
||||
.setComments("""
|
||||
{@snippet file="%s":
|
||||
First line // @highlight :
|
||||
}
|
||||
""".formatted(goodFile)))
|
||||
// TODO: these two hybrids are to test what *this* test should not test.
|
||||
// Add a test that checks that an error in either part
|
||||
// of a hybrid snippet causes the snippet to fail (property-based testing)
|
||||
.write(srcDir);
|
||||
addSnippetFile(srcDir, "pkg", goodFile, """
|
||||
First line // @highlight
|
||||
""");
|
||||
addSnippetFile(srcDir, "pkg", badFile, """
|
||||
First line // @highlight :
|
||||
""");
|
||||
addSnippetFile(srcDir, "pkg", badFile2, """
|
||||
First line // @highlight :
|
||||
""");
|
||||
javadoc("-d", outDir.toString(),
|
||||
"-sourcepath", srcDir.toString(),
|
||||
"pkg");
|
||||
checkExit(Exit.ERROR);
|
||||
checkOutput(Output.OUT, true,
|
||||
"""
|
||||
A.java:5: error: snippet markup: tag refers to non-existent lines
|
||||
First line // @highlight :
|
||||
^""",
|
||||
"""
|
||||
A.java:24: error: snippet markup: tag refers to non-existent lines
|
||||
First line // @highlight :
|
||||
^""",
|
||||
"""
|
||||
%s:1: error: snippet markup: tag refers to non-existent lines
|
||||
First line // @highlight :
|
||||
^""".formatted(badFile),
|
||||
"""
|
||||
%s:1: error: snippet markup: tag refers to non-existent lines
|
||||
First line // @highlight :
|
||||
^""".formatted(badFile2));
|
||||
checkNoCrashes();
|
||||
}
|
||||
|
||||
private void testPositive(Path base, List<TestCase> testCases)
|
||||
throws IOException {
|
||||
StringBuilder methods = new StringBuilder();
|
||||
forEachNumbered(testCases, (i, n) -> {
|
||||
String r = i.region.isBlank() ? "" : "region=" + i.region;
|
||||
var methodDef = """
|
||||
|
||||
/**
|
||||
{@snippet %s:
|
||||
%s}*/
|
||||
public void case%s() {}
|
||||
""".formatted(r, i.input, n);
|
||||
methods.append(methodDef);
|
||||
});
|
||||
var classDef = """
|
||||
public class A {
|
||||
%s
|
||||
}
|
||||
""".formatted(methods.toString());
|
||||
Path src = Files.createDirectories(base.resolve("src"));
|
||||
tb.writeJavaFiles(src, classDef);
|
||||
javadoc("-d", base.resolve("out").toString(),
|
||||
"-sourcepath", src.toString(),
|
||||
src.resolve("A.java").toString());
|
||||
checkExit(Exit.OK);
|
||||
checkNoCrashes();
|
||||
forEachNumbered(testCases, (t, index) -> {
|
||||
String html = """
|
||||
<span class="element-name">case%s</span>()</div>
|
||||
<div class="block">
|
||||
%s
|
||||
</div>""".formatted(index, getSnippetHtmlRepresentation("A.html", t.expectedOutput()));
|
||||
checkOutput("A.html", true, html);
|
||||
});
|
||||
}
|
||||
|
||||
// FIXME: move error (i.e. negative) tests from TestSnippetTag to here
|
||||
|
||||
// @start region=<name> ... @end [region|region=<name>]
|
||||
@Test
|
||||
public void testStart(Path base) throws Exception {
|
||||
var testCases = new ArrayList<TestCase>();
|
||||
for (var variant : generateStartEndVariants()) {
|
||||
var t = new TestCase(variant.region,
|
||||
"""
|
||||
First line
|
||||
Second line // ###START
|
||||
Third line
|
||||
Fourth line // ###END
|
||||
Fifth line
|
||||
""".replaceFirst("###START", variant.start)
|
||||
.replaceFirst("###END", variant.end),
|
||||
"""
|
||||
Second line
|
||||
Third line
|
||||
Fourth line""");
|
||||
testCases.add(t);
|
||||
}
|
||||
testPositive(base, testCases);
|
||||
}
|
||||
|
||||
private static String link(boolean linkPlain,
|
||||
String targetReference,
|
||||
String content)
|
||||
throws UncheckedIOException {
|
||||
|
||||
// The HTML <a> tag generated from the @link snippet markup tag is the
|
||||
// same as that of the {@link} Standard doclet tag. This is specified
|
||||
// and can be used for comparison and testing.
|
||||
|
||||
// generate documentation for {@link} to grab its HTML <a> tag;
|
||||
// generate documentation at low cost and do not interfere with the
|
||||
// calling test state; for that, do not create file trees, do not write
|
||||
// to std out/err, and generally try to keep everything in memory
|
||||
|
||||
String source = """
|
||||
/** {@link %s %s} */
|
||||
public interface A { }
|
||||
""".formatted(targetReference, content);
|
||||
|
||||
JavaFileObject src = new JavaFileObject() {
|
||||
@Override
|
||||
public Kind getKind() {return Kind.SOURCE;}
|
||||
|
||||
@Override
|
||||
public boolean isNameCompatible(String simpleName, Kind kind) {
|
||||
return kind == Kind.SOURCE;
|
||||
}
|
||||
|
||||
@Override
|
||||
public NestingKind getNestingKind() {return NestingKind.TOP_LEVEL;}
|
||||
|
||||
@Override
|
||||
public Modifier getAccessLevel() {return Modifier.PUBLIC;}
|
||||
|
||||
@Override
|
||||
public URI toUri() {throw new UnsupportedOperationException();}
|
||||
|
||||
@Override
|
||||
public String getName() {return "A.java";}
|
||||
|
||||
@Override
|
||||
public InputStream openInputStream() {
|
||||
return new ByteArrayInputStream(source.getBytes(StandardCharsets.UTF_8));
|
||||
}
|
||||
|
||||
@Override
|
||||
public OutputStream openOutputStream() {
|
||||
throw new UnsupportedOperationException("Read only");
|
||||
}
|
||||
|
||||
@Override
|
||||
public Reader openReader(boolean ignoreEncodingErrors) {
|
||||
return new StringReader(source);
|
||||
}
|
||||
|
||||
@Override
|
||||
public CharSequence getCharContent(boolean ignoreEncodingErrors) {
|
||||
return source;
|
||||
}
|
||||
|
||||
@Override
|
||||
public Writer openWriter() {
|
||||
throw new UnsupportedOperationException("Read only");
|
||||
}
|
||||
|
||||
@Override
|
||||
public long getLastModified() {
|
||||
return 0;
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean delete() {
|
||||
throw new UnsupportedOperationException("Read only");
|
||||
}
|
||||
};
|
||||
|
||||
var documentationTool = ToolProvider.getSystemDocumentationTool();
|
||||
var writer = new StringWriter();
|
||||
|
||||
// FileManager has to be StandardJavaFileManager; JavaDoc is adamant about it
|
||||
class InMemoryFileManager extends ToolBox.MemoryFileManager
|
||||
implements StandardJavaFileManager {
|
||||
|
||||
private final StandardJavaFileManager delegate = documentationTool
|
||||
.getStandardFileManager(null, null, null);
|
||||
|
||||
@Override
|
||||
public Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles(Iterable<? extends File> files) {
|
||||
return delegate.getJavaFileObjectsFromFiles(files);
|
||||
}
|
||||
|
||||
@Override
|
||||
public Iterable<? extends JavaFileObject> getJavaFileObjects(File... files) {
|
||||
return delegate.getJavaFileObjects(files);
|
||||
}
|
||||
|
||||
@Override
|
||||
public Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings(Iterable<String> names) {
|
||||
return delegate.getJavaFileObjectsFromStrings(names);
|
||||
}
|
||||
|
||||
@Override
|
||||
public Iterable<? extends JavaFileObject> getJavaFileObjects(String... names) {
|
||||
return delegate.getJavaFileObjects(names);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void setLocation(Location location, Iterable<? extends File> files) throws IOException {
|
||||
delegate.setLocation(location, files);
|
||||
}
|
||||
|
||||
@Override
|
||||
public Iterable<? extends File> getLocation(Location location) {
|
||||
return delegate.getLocation(location);
|
||||
}
|
||||
|
||||
@Override
|
||||
public FileObject getFileForOutput(Location location,
|
||||
String packageName,
|
||||
String relativeName,
|
||||
FileObject sibling) {
|
||||
return getJavaFileForOutput(location, packageName + relativeName, JavaFileObject.Kind.OTHER, null);
|
||||
}
|
||||
}
|
||||
try {
|
||||
var fileManager = new InMemoryFileManager();
|
||||
fileManager.setLocation(DOCUMENTATION_OUTPUT, Collections.singleton(new File(".")));
|
||||
// exclude extraneous output; we're only after @link
|
||||
List<String> options = List.of("--limit-modules", "java.base",
|
||||
"-quiet", "-nohelp", "-noindex", "-nonavbar", "-nosince",
|
||||
"-notimestamp", "-notree", "-Xdoclint:none");
|
||||
var documentationTask = documentationTool.getTask(null, fileManager,
|
||||
null, null, options, List.of(src));
|
||||
if (!documentationTask.call()) {
|
||||
throw new IOException(writer.toString());
|
||||
}
|
||||
String output = fileManager.getFileString(DOCUMENTATION_OUTPUT, "A.html");
|
||||
// use the [^<>] regex to select HTML elements that immediately enclose "content"
|
||||
Matcher m = Pattern.compile("(?is)<a href=\"[^<>]*\" title=\"[^<>]*\" class=\"[^<>]*\"><code>"
|
||||
+ content + "</code></a>").matcher(output);
|
||||
if (!m.find()) {
|
||||
throw new IOException(output);
|
||||
}
|
||||
return m.group(0);
|
||||
} catch (IOException e) {
|
||||
throw new UncheckedIOException(e);
|
||||
}
|
||||
}
|
||||
|
||||
private static String replace(String source,
|
||||
String regex,
|
||||
Function<MatchResult, String> replacer) {
|
||||
return Pattern.compile(regex).matcher(source).replaceAll(replacer);
|
||||
}
|
||||
|
||||
private static final AtomicLong UNIQUE_INTEGER_NUMBER = new AtomicLong();
|
||||
|
||||
private static Collection<StartEndVariant> generateStartEndVariants() {
|
||||
var variants = new ArrayList<StartEndVariant>();
|
||||
for (var start : startAttributes())
|
||||
for (var end : endAttributes()) {
|
||||
var region = uniqueValue();
|
||||
var v = new StartEndVariant(region,
|
||||
"@start" + start.apply(region),
|
||||
"@end" + end.apply(region));
|
||||
variants.add(v);
|
||||
}
|
||||
return variants;
|
||||
}
|
||||
|
||||
private static String uniqueValue() {
|
||||
return "auto_generated_value_" + UNIQUE_INTEGER_NUMBER.incrementAndGet();
|
||||
}
|
||||
|
||||
public static Collection<Function<String, String>> startAttributes() {
|
||||
return attributes("region");
|
||||
}
|
||||
|
||||
private static Collection<Function<String, String>> endAttributes() {
|
||||
var variants = new ArrayList<Function<String, String>>();
|
||||
variants.add(value -> "");
|
||||
variants.add(value -> " region");
|
||||
variants.addAll(attributes("region"));
|
||||
return variants;
|
||||
}
|
||||
|
||||
private static Collection<Function<String, String>> attributes(String name) {
|
||||
var variants = new ArrayList<Function<String, String>>();
|
||||
for (var whitespace1 : List.of(" ", " "))
|
||||
for (var whitespace2 : List.of("", " "))
|
||||
for (var quote : List.of("", "'", "\""))
|
||||
for (var whitespace3 : List.of("", " ")) {
|
||||
Function<String, String> f = value ->
|
||||
whitespace1 + name + whitespace2
|
||||
+ "=" + whitespace3 + (quote + value + quote);
|
||||
variants.add(f);
|
||||
}
|
||||
return variants;
|
||||
}
|
||||
|
||||
record StartEndVariant(String region, String start, String end) {}
|
||||
}
|
||||
@ -0,0 +1,220 @@
|
||||
/*
|
||||
* Copyright (c) 2021, 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 8266666
|
||||
* @summary Implementation for snippets
|
||||
* @library /tools/lib ../../lib
|
||||
* @modules jdk.compiler/com.sun.tools.javac.api
|
||||
* jdk.compiler/com.sun.tools.javac.main
|
||||
* jdk.javadoc/jdk.javadoc.internal.tool
|
||||
* @build javadoc.tester.* toolbox.ToolBox toolbox.ModuleBuilder builder.ClassBuilder
|
||||
* @run main TestSnippetPathOption
|
||||
*/
|
||||
|
||||
import java.io.File;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.nio.file.Paths;
|
||||
import java.util.stream.Collectors;
|
||||
import java.util.stream.Stream;
|
||||
|
||||
public class TestSnippetPathOption extends SnippetTester {
|
||||
|
||||
public static void main(String... args) throws Exception {
|
||||
new TestSnippetPathOption().runTests(m -> new Object[]{Paths.get(m.getName())});
|
||||
}
|
||||
|
||||
/*
|
||||
# snippet-files snippet-path result
|
||||
---+--------------+--------------+---------------------
|
||||
1 + + snippet-files
|
||||
2 + invalid snippet-files
|
||||
3 - + snippet-path
|
||||
4 - invalid error
|
||||
*/
|
||||
|
||||
@Test
|
||||
public void test1(Path base) throws Exception {
|
||||
Path src = Files.createDirectories(base.resolve("src"));
|
||||
tb.createDirectories(src.resolve("directoryA"), src.resolve("directoryB"));
|
||||
tb.writeFile(src.resolve("directoryA/mysnippet.txt"), "Hello, directoryA!");
|
||||
tb.writeFile(src.resolve("directoryB/mysnippet.txt"), "Hello, directoryB!");
|
||||
tb.writeFile(src.resolve("pkg/snippet-files/mysnippet.txt"), "Hello, snippet-files!");
|
||||
tb.writeJavaFiles(src, """
|
||||
package pkg;
|
||||
|
||||
/** {@snippet file="mysnippet.txt"} */
|
||||
public class X { }
|
||||
""");
|
||||
String snippetPathValue = Stream.of("directoryA", "directoryB")
|
||||
.map(src::resolve)
|
||||
.map(Path::toAbsolutePath)
|
||||
.map(Path::toString)
|
||||
.collect(Collectors.joining(File.pathSeparator));
|
||||
javadoc("-d", base.resolve("out").toString(),
|
||||
"--snippet-path", snippetPathValue,
|
||||
"-sourcepath", src.toString(),
|
||||
"pkg");
|
||||
checkExit(Exit.OK);
|
||||
checkOutput("pkg/X.html", true, "Hello, snippet-files!");
|
||||
checkOutput("pkg/X.html", false, "Hello, directoryA!");
|
||||
checkOutput("pkg/X.html", false, "Hello, directoryB!");
|
||||
}
|
||||
|
||||
@Test
|
||||
public void test2(Path base) throws Exception {
|
||||
Path src = Files.createDirectories(base.resolve("src"));
|
||||
tb.createDirectories(src.resolve("directoryA"), src.resolve("directoryB"));
|
||||
tb.writeFile(src.resolve("pkg/snippet-files/mysnippet.txt"), "Hello, snippet-files!");
|
||||
tb.writeJavaFiles(src, """
|
||||
package pkg;
|
||||
|
||||
/** {@snippet file="mysnippet.txt"} */
|
||||
public class X { }
|
||||
""");
|
||||
String snippetPathValue = Stream.of("directoryA", "directoryB")
|
||||
.map(src::resolve)
|
||||
.map(Path::toAbsolutePath)
|
||||
.map(Path::toString)
|
||||
.collect(Collectors.joining(File.pathSeparator));
|
||||
javadoc("-d", base.resolve("out").toString(),
|
||||
"--snippet-path", snippetPathValue,
|
||||
"-sourcepath", src.toString(),
|
||||
"pkg");
|
||||
checkExit(Exit.OK);
|
||||
checkOutput("pkg/X.html", true, "Hello, snippet-files!");
|
||||
}
|
||||
|
||||
@Test
|
||||
public void test3(Path base) throws Exception {
|
||||
Path src = Files.createDirectories(base.resolve("src"));
|
||||
tb.createDirectories(src.resolve("directoryA"), src.resolve("directoryB"));
|
||||
tb.writeFile(src.resolve("directoryA/mysnippet.txt"), "Hello, directoryA!");
|
||||
tb.writeFile(src.resolve("directoryB/mysnippet.txt"), "Hello, directoryB!");
|
||||
tb.writeJavaFiles(src, """
|
||||
package pkg;
|
||||
|
||||
/** {@snippet file="mysnippet.txt"} */
|
||||
public class X { }
|
||||
""");
|
||||
String snippetPathValue = Stream.of("directoryA", "directoryB")
|
||||
.map(src::resolve)
|
||||
.map(Path::toAbsolutePath)
|
||||
.map(Path::toString)
|
||||
.collect(Collectors.joining(File.pathSeparator));
|
||||
javadoc("-d", base.resolve("out").toString(),
|
||||
"--snippet-path", snippetPathValue,
|
||||
"-sourcepath", src.toString(),
|
||||
"pkg");
|
||||
checkExit(Exit.OK);
|
||||
checkOutput("pkg/X.html", true, "Hello, directoryA!");
|
||||
checkOutput("pkg/X.html", false, "Hello, directoryB!");
|
||||
}
|
||||
|
||||
@Test
|
||||
public void test4(Path base) throws Exception {
|
||||
Path src = Files.createDirectories(base.resolve("src"));
|
||||
tb.writeJavaFiles(src, """
|
||||
package pkg;
|
||||
|
||||
/** {@snippet file="mysnippet.txt"} */
|
||||
public class X { }
|
||||
""");
|
||||
String snippetPathValue = Stream.of("directoryA", "directoryB")
|
||||
.map(src::resolve)
|
||||
.map(Path::toAbsolutePath)
|
||||
.map(Path::toString)
|
||||
.collect(Collectors.joining(File.pathSeparator));
|
||||
javadoc("-d", base.resolve("out").toString(),
|
||||
"--snippet-path", snippetPathValue,
|
||||
"-sourcepath", src.toString(),
|
||||
"pkg");
|
||||
checkExit(Exit.ERROR);
|
||||
}
|
||||
|
||||
/*
|
||||
* Tests that the elements of the snippet path are iteratively searched
|
||||
* until the file is found. In particular, tests that if the file is not
|
||||
* immediately found, the search is not abandoned.
|
||||
*/
|
||||
@Test
|
||||
public void testSearchPath(Path base) throws Exception {
|
||||
Path src = Files.createDirectories(base.resolve("src"));
|
||||
tb.createDirectories(src.resolve("directoryA"), src.resolve("directoryB"));
|
||||
// do not put snippet in directoryA; only put snippet in directoryB
|
||||
tb.writeFile(src.resolve("directoryB/mysnippet.txt"), "Hello, directoryB!");
|
||||
tb.writeJavaFiles(src, """
|
||||
package pkg;
|
||||
|
||||
/** {@snippet file="mysnippet.txt"} */
|
||||
public class X { }
|
||||
""");
|
||||
// directoryA goes first, assuming that paths are searched in
|
||||
// the same order they are specified in
|
||||
String snippetPathValue = Stream.of("directoryA", "directoryB")
|
||||
.map(src::resolve)
|
||||
.map(Path::toAbsolutePath)
|
||||
.map(Path::toString)
|
||||
.collect(Collectors.joining(File.pathSeparator));
|
||||
javadoc("-d", base.resolve("out").toString(),
|
||||
"--snippet-path", snippetPathValue,
|
||||
"-sourcepath", src.toString(),
|
||||
"pkg");
|
||||
checkExit(Exit.OK);
|
||||
checkOutput("pkg/X.html", true, "Hello, directoryB!");
|
||||
}
|
||||
|
||||
/*
|
||||
* Tests translation from FQN (the "class" attribute) to file path
|
||||
* (the "file" attribute).
|
||||
*/
|
||||
@Test
|
||||
public void testClassToFile(Path base) throws Exception {
|
||||
Path src = Files.createDirectories(base.resolve("src"));
|
||||
Path directoryA = Files.createDirectories(src.resolve("directoryA"));
|
||||
tb.writeJavaFiles(directoryA, """
|
||||
package com.example.snippet;
|
||||
|
||||
public interface Y { }
|
||||
""");
|
||||
tb.writeJavaFiles(src, """
|
||||
package pkg;
|
||||
|
||||
/** {@snippet class="com.example.snippet.Y"} */
|
||||
public class X { }
|
||||
""");
|
||||
String snippetPathValue = Stream.of("directoryA")
|
||||
.map(src::resolve)
|
||||
.map(Path::toAbsolutePath)
|
||||
.map(Path::toString)
|
||||
.collect(Collectors.joining(File.pathSeparator));
|
||||
javadoc("-d", base.resolve("out").toString(),
|
||||
"--snippet-path", snippetPathValue,
|
||||
"-sourcepath", src.toString(),
|
||||
"pkg");
|
||||
checkExit(Exit.OK);
|
||||
checkOutput("pkg/X.html", true, "public interface Y { }");
|
||||
}
|
||||
}
|
||||
@ -33,27 +33,21 @@
|
||||
* @run main TestSnippetTag
|
||||
*/
|
||||
|
||||
import builder.ClassBuilder;
|
||||
import builder.ClassBuilder.MethodBuilder;
|
||||
import javadoc.tester.JavadocTester;
|
||||
import toolbox.ModuleBuilder;
|
||||
import toolbox.ToolBox;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.io.UncheckedIOException;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.nio.file.Paths;
|
||||
import java.nio.file.StandardOpenOption;
|
||||
import java.util.Arrays;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import java.util.concurrent.atomic.AtomicInteger;
|
||||
import java.util.function.Function;
|
||||
import java.util.function.ObjIntConsumer;
|
||||
import java.util.regex.Matcher;
|
||||
import java.util.regex.Pattern;
|
||||
import java.util.stream.Stream;
|
||||
|
||||
import builder.ClassBuilder;
|
||||
import builder.ClassBuilder.MethodBuilder;
|
||||
import toolbox.ModuleBuilder;
|
||||
|
||||
// FIXME
|
||||
// 0. Add tests for snippets in all types of elements: e.g., fields
|
||||
@ -63,7 +57,22 @@ import java.util.stream.Stream;
|
||||
// 3. Add tests for hybrid snippets
|
||||
|
||||
/*
|
||||
* General notes.
|
||||
* General notes
|
||||
* =============
|
||||
*
|
||||
* To simplify maintenance of this test suite, a test name uses a convention.
|
||||
* By convention, a test name is a concatenation of the following parts:
|
||||
*
|
||||
* 1. "test"
|
||||
* 2. ("Positive", "Negative")
|
||||
* 3. ("Inline", "External", "Hybrid")
|
||||
* 4. ("Tag", "Markup")
|
||||
* 5. <custom string>
|
||||
*
|
||||
* A test can be either positive or negative; it cannot be both or neither.
|
||||
* A test can exercise inline, external or hybrid variant or any combination
|
||||
* thereof, including none at all. A test can exercise tag syntax, markup syntax
|
||||
* or both.
|
||||
*
|
||||
* 1. Some of the below tests could benefit from using a combinatorics library
|
||||
* as they are otherwise very wordy.
|
||||
@ -73,35 +82,27 @@ import java.util.stream.Stream;
|
||||
* if x is passed to that method additionally N times: JavadocTester.checkOutput(x, x, ..., x).
|
||||
* This is because a single occurrence of x in the output will be matched N times.
|
||||
*/
|
||||
public class TestSnippetTag extends JavadocTester {
|
||||
|
||||
private final ToolBox tb = new ToolBox();
|
||||
|
||||
private TestSnippetTag() { }
|
||||
public class TestSnippetTag extends SnippetTester {
|
||||
|
||||
public static void main(String... args) throws Exception {
|
||||
new TestSnippetTag().runTests(m -> new Object[]{Paths.get(m.getName())});
|
||||
}
|
||||
|
||||
/*
|
||||
* Make sure the "id" and "lang" attributes defined in JEP 413 are rendered
|
||||
* properly as recommended by the HTML5 specification.
|
||||
* Make sure the "id" and "lang" attributes defined in JEP 413 are translated
|
||||
* to HTML. In particular, verify that the "lang" attribute is translated
|
||||
* to a value added to the "class" attribute as recommended by the HTML5 specification:
|
||||
* https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element
|
||||
*/
|
||||
@Test
|
||||
public void testIdAndLangAttributes(Path base) throws IOException {
|
||||
public void testPositiveInlineTag_IdAndLangAttributes(Path base) throws IOException {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
|
||||
// A record of a snippet content and matching expected attribute values
|
||||
record SnippetAttributes(String content, String id, String lang) {
|
||||
public String idAttribute() {
|
||||
return id == null ? "" : " id=\"" + id + "\"";
|
||||
}
|
||||
public String langAttribute() {
|
||||
return lang == null ? "" : " class=\"language-" + lang + "\"";
|
||||
}
|
||||
}
|
||||
record SnippetAttributes(String content, String id, String lang) { }
|
||||
|
||||
// TODO: use combinatorial methods, e.g. just like in TestSnippetMarkup
|
||||
final var snippets = List.of(
|
||||
new SnippetAttributes("""
|
||||
{@snippet id="foo1" :
|
||||
@ -218,29 +219,29 @@ public class TestSnippetTag extends JavadocTester {
|
||||
checkExit(Exit.OK);
|
||||
checkLinks();
|
||||
for (int j = 0; j < snippets.size(); j++) {
|
||||
SnippetAttributes snippet = snippets.get(j);
|
||||
var attr = snippets.get(j);
|
||||
var snippetHtml = getSnippetHtmlRepresentation("pkg/A.html", " Hello, Snippet!\n",
|
||||
Optional.ofNullable(attr.lang()), Optional.ofNullable(attr.id()));
|
||||
checkOutput("pkg/A.html", true,
|
||||
"""
|
||||
<span class="element-name">case%s</span>()</div>
|
||||
<div class="block">A method.
|
||||
\s
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySni\
|
||||
ppet(this)"><span data-copied="Copied!">Copy</span><img src="../copy.svg" al\
|
||||
t="Copy"></button>
|
||||
<pre class="snippet"%s><code%s> Hello, Snippet!
|
||||
</code></pre>
|
||||
</div>
|
||||
""".formatted(j, snippet.idAttribute(), snippet.langAttribute()));
|
||||
%s
|
||||
""".formatted(j, snippetHtml));
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* Make sure the lang attribute is derived correctly from the snippet source file
|
||||
* for external snippets when it is not defined in the snippet. Defining the lang
|
||||
* attribute in the snippet should always override this mechanism.
|
||||
* If the "lang" attribute is absent in the snippet tag for an external snippet,
|
||||
* then the "class" attribute is derived from the snippet source file extension.
|
||||
*
|
||||
* If the "class" attribute can be derived both from the "lang" attribute and
|
||||
* the file extension, then it is derived from the "lang" attribute.
|
||||
*/
|
||||
// TODO: restructure this as a list of TestCase records
|
||||
@Test
|
||||
public void testExternalImplicitAttributes(Path base) throws IOException {
|
||||
public void testPositiveInlineExternalTagMarkup_ImplicitAttributes(Path base) throws IOException {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
|
||||
@ -276,60 +277,28 @@ public class TestSnippetTag extends JavadocTester {
|
||||
"com.example");
|
||||
checkExit(Exit.OK);
|
||||
checkLinks();
|
||||
checkOutput("com/example/Cls.html", true,
|
||||
"""
|
||||
<pre class="snippet" id="snippet1"><code class="language-java">
|
||||
System.out.println(msg);
|
||||
</code></pre>""",
|
||||
"""
|
||||
<pre class="snippet" id="snippet2"><code class="language-java">
|
||||
System.out.println(msg);
|
||||
</code></pre>""",
|
||||
"""
|
||||
<pre class="snippet" id="snippet3"><code class="language-none">
|
||||
System.out.println(msg);
|
||||
</code></pre>""",
|
||||
"""
|
||||
<pre class="snippet" id="snippet4"><code class="language-none">
|
||||
System.out.println(msg);
|
||||
</code></pre>""",
|
||||
"""
|
||||
<pre class="snippet" id="snippet5"><code>
|
||||
System.out.println(msg);
|
||||
</code></pre>""",
|
||||
"""
|
||||
<pre class="snippet" id="snippet6"><code>
|
||||
System.out.println(msg);
|
||||
</code></pre>""",
|
||||
"""
|
||||
<pre class="snippet" id="snippet7"><code class="language-properties">user=jane
|
||||
home=/home/jane
|
||||
</code></pre>""",
|
||||
"""
|
||||
<pre class="snippet" id="snippet8"><code class="language-none">user=jane
|
||||
home=/home/jane
|
||||
</code></pre>""",
|
||||
"""
|
||||
<pre class="snippet" id="snippet9"><code>user=jane
|
||||
home=/home/jane
|
||||
</code></pre>""");
|
||||
}
|
||||
final var javaContent = """
|
||||
|
||||
/*
|
||||
* This is a convenience method to iterate through a list.
|
||||
* Unlike List.forEach, this method provides the consumer not only with an
|
||||
* element but also that element's index.
|
||||
*
|
||||
* See JDK-8184707.
|
||||
*/
|
||||
private static <T> void forEachNumbered(List<T> list, ObjIntConsumer<? super T> action) {
|
||||
for (var iterator = list.listIterator(); iterator.hasNext(); ) {
|
||||
action.accept(iterator.next(), iterator.previousIndex());
|
||||
}
|
||||
System.out.println(msg);
|
||||
""";
|
||||
final var propertiesContent = """
|
||||
user=jane
|
||||
home=/home/jane
|
||||
""";
|
||||
checkOutput("com/example/Cls.html", true,
|
||||
getSnippetHtmlRepresentation("com/example/Cls.html", javaContent, Optional.of("java"), Optional.of("snippet1")),
|
||||
getSnippetHtmlRepresentation("com/example/Cls.html", javaContent, Optional.of("java"), Optional.of("snippet2")),
|
||||
getSnippetHtmlRepresentation("com/example/Cls.html", javaContent, Optional.of("none"), Optional.of("snippet3")),
|
||||
getSnippetHtmlRepresentation("com/example/Cls.html", javaContent, Optional.of("none"), Optional.of("snippet4")),
|
||||
getSnippetHtmlRepresentation("com/example/Cls.html", javaContent, Optional.empty(), Optional.of("snippet5")),
|
||||
getSnippetHtmlRepresentation("com/example/Cls.html", javaContent, Optional.empty(), Optional.of("snippet6")),
|
||||
getSnippetHtmlRepresentation("com/example/user.properties", propertiesContent, Optional.of("properties"), Optional.of("snippet7")),
|
||||
getSnippetHtmlRepresentation("com/example/user.properties", propertiesContent, Optional.of("none"), Optional.of("snippet8")),
|
||||
getSnippetHtmlRepresentation("com/example/user.properties", propertiesContent, Optional.empty(), Optional.of("snippet9")));
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testBadTagSyntax(Path base) throws IOException {
|
||||
public void testNegativeInlineTag_BadTagSyntax(Path base) throws IOException {
|
||||
// TODO consider improving diagnostic output by providing more specific
|
||||
// error messages and better positioning the caret (depends on JDK-8273244)
|
||||
|
||||
@ -666,50 +635,13 @@ public class TestSnippetTag extends JavadocTester {
|
||||
));
|
||||
}
|
||||
|
||||
// TODO This is a temporary method; it should be removed after JavadocTester has provided similar functionality (JDK-8273154).
|
||||
private void checkOrder(Output output, String... strings) {
|
||||
String outputString = getOutput(output);
|
||||
int prevIndex = -1;
|
||||
for (String s : strings) {
|
||||
s = s.replace("\n", NL); // normalize new lines
|
||||
int currentIndex = outputString.indexOf(s, prevIndex + 1);
|
||||
checking("output: " + output + ": " + s + " at index " + currentIndex);
|
||||
if (currentIndex == -1) {
|
||||
failed(output + ": " + s + " not found.");
|
||||
continue;
|
||||
}
|
||||
if (currentIndex > prevIndex) {
|
||||
passed(output + ": " + " is in the correct order");
|
||||
} else {
|
||||
failed(output + ": " + " is in the wrong order.");
|
||||
}
|
||||
prevIndex = currentIndex;
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* When checking for errors, it is important not to confuse one error with
|
||||
* another. This method checks that there are no crashes (which are also
|
||||
* errors) by checking for stack traces. We never expect crashes.
|
||||
*/
|
||||
private void checkNoCrashes() {
|
||||
checking("check crashes");
|
||||
Matcher matcher = Pattern.compile("\s*at.*\\(.*\\.java:\\d+\\)")
|
||||
.matcher(getOutput(Output.STDERR));
|
||||
if (!matcher.find()) {
|
||||
passed("");
|
||||
} else {
|
||||
failed("Looks like a stacktrace: " + matcher.group());
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* A colon that is not separated from a tag name by whitespace is considered
|
||||
* a part of that name. This behavior is historical. For more context see,
|
||||
* for example, JDK-4750173.
|
||||
*/
|
||||
@Test
|
||||
public void testUnknownTag(Path base) throws IOException {
|
||||
public void testNegativeInlineTagUnknownTag(Path base) throws IOException {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
final var unknownTags = List.of(
|
||||
@ -746,7 +678,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testInline(Path base) throws Exception {
|
||||
public void testPositiveInlineTag(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
|
||||
@ -948,16 +880,12 @@ public class TestSnippetTag extends JavadocTester {
|
||||
"""
|
||||
<span class="element-name">case%s</span>()</div>
|
||||
<div class="block">
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySni\
|
||||
ppet(this)"><span data-copied="Copied!">Copy</span><img src="../copy.svg" al\
|
||||
t="Copy"></button>
|
||||
<pre class="snippet"><code>%s</code></pre>
|
||||
</div>""".formatted(id, t.expectedOutput()));
|
||||
%s""".formatted(id, getSnippetHtmlRepresentation("pkg/A.html", t.expectedOutput())));
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testExternalFile(Path base) throws Exception {
|
||||
public void testPositiveExternalTag_File(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
|
||||
@ -1044,30 +972,12 @@ public class TestSnippetTag extends JavadocTester {
|
||||
"""
|
||||
<span class="element-name">case%s</span>()</div>
|
||||
<div class="block">
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySni\
|
||||
ppet(this)"><span data-copied="Copied!">Copy</span><img src="../copy.svg" al\
|
||||
t="Copy"></button>
|
||||
<pre class="snippet"><code>%s</code></pre>
|
||||
</div>""".formatted(index, expectedOutput));
|
||||
%s""".formatted(index, getSnippetHtmlRepresentation("pkg/A.html", expectedOutput)));
|
||||
});
|
||||
}
|
||||
|
||||
// TODO:
|
||||
// Explore the toolbox.ToolBox.writeFile and toolbox.ToolBox.writeJavaFiles methods:
|
||||
// see if any of them could be used instead of this one
|
||||
private void addSnippetFile(Path srcDir, String packageName, String fileName, String content) throws UncheckedIOException {
|
||||
String[] components = packageName.split("\\.");
|
||||
Path snippetFiles = Path.of(components[0], Arrays.copyOfRange(components, 1, components.length)).resolve("snippet-files");
|
||||
try {
|
||||
Path p = Files.createDirectories(srcDir.resolve(snippetFiles));
|
||||
Files.writeString(p.resolve(fileName), content, StandardOpenOption.CREATE_NEW);
|
||||
} catch (IOException e) {
|
||||
throw new UncheckedIOException(e);
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testInlineSnippetInDocFiles(Path base) throws IOException {
|
||||
public void testPositiveInlineTag_InDocFiles(Path base) throws IOException {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
// If there is no *.java files, javadoc will not create an output
|
||||
@ -1109,7 +1019,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testExternalSnippetInDocFiles(Path base) throws IOException {
|
||||
public void testPositiveExternalTag_InDocFiles(Path base) throws IOException {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
// If there is no *.java files, javadoc will not create an output
|
||||
@ -1151,7 +1061,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testExternalFileNotFound(Path base) throws Exception {
|
||||
public void testNegativeExternalTag_FileNotFound(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var fileName = "text.txt";
|
||||
@ -1174,8 +1084,8 @@ public class TestSnippetTag extends JavadocTester {
|
||||
checkNoCrashes();
|
||||
}
|
||||
|
||||
@Test // TODO perhaps this could be unified with testExternalFile
|
||||
public void testExternalFileModuleSourcePath(Path base) throws Exception {
|
||||
@Test // TODO perhaps this could be unified with testPositiveExternalTagFile
|
||||
public void testNegativeExternalTag_FileModuleSourcePath(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var fileName = "snippet.txt";
|
||||
@ -1200,8 +1110,8 @@ public class TestSnippetTag extends JavadocTester {
|
||||
checkExit(Exit.OK);
|
||||
}
|
||||
|
||||
@Test // TODO perhaps this could be unified with testExternalFileNotFound
|
||||
public void testExternalFileNotFoundModuleSourcePath(Path base) throws Exception {
|
||||
@Test // TODO perhaps this could be unified with testNegativeExternalTagFileNotFound
|
||||
public void testNegativeExternalTag_FileNotFoundModuleSourcePath(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var fileName = "text.txt";
|
||||
@ -1230,7 +1140,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testNoContents(Path base) throws Exception {
|
||||
public void testNegativeTag_NoContents(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
new ClassBuilder(tb, "pkg.A")
|
||||
@ -1250,7 +1160,37 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testConflict20(Path base) throws Exception {
|
||||
public void testNegativeExternalTagMarkup(Path base) throws Exception {
|
||||
// External snippet issues are handled similarly to those of internal snippet
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
addSnippetFile(srcDir, "pkg", "file.txt", """
|
||||
// @start
|
||||
"""
|
||||
);
|
||||
ClassBuilder classBuilder = new ClassBuilder(tb, "pkg.A")
|
||||
.setModifiers("public", "class")
|
||||
.addMembers(
|
||||
MethodBuilder
|
||||
.parse("public void case0() { }")
|
||||
.setComments("""
|
||||
{@snippet file="file.txt"}
|
||||
"""));
|
||||
classBuilder.write(srcDir);
|
||||
javadoc("-d", outDir.toString(),
|
||||
"-sourcepath", srcDir.toString(),
|
||||
"pkg");
|
||||
checkExit(Exit.ERROR);
|
||||
checkOutput(Output.OUT, true,
|
||||
"""
|
||||
: error: snippet markup: missing attribute "region"
|
||||
// @start
|
||||
^""");
|
||||
checkNoCrashes();
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testNegativeInlineTag_AttributeConflict20(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
new ClassBuilder(tb, "pkg.A")
|
||||
@ -1276,7 +1216,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testConflict30(Path base) throws Exception {
|
||||
public void testNegativeInlineTag_AttributeConflict30(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
new ClassBuilder(tb, "pkg.A")
|
||||
@ -1297,21 +1237,8 @@ public class TestSnippetTag extends JavadocTester {
|
||||
checkNoCrashes();
|
||||
}
|
||||
|
||||
// TODO: perhaps this method could be added to JavadocTester
|
||||
private void checkOutputEither(Output out, String first, String... other) {
|
||||
checking("checkOutputEither");
|
||||
String output = getOutput(out);
|
||||
Stream<String> strings = Stream.concat(Stream.of(first), Stream.of(other));
|
||||
Optional<String> any = strings.filter(output::contains).findAny();
|
||||
if (any.isPresent()) {
|
||||
passed(": following text is found:\n" + any.get());
|
||||
} else {
|
||||
failed(": nothing found");
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testConflict60(Path base) throws Exception {
|
||||
public void testNegativeInlineTag_AttributeConflict60(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
new ClassBuilder(tb, "pkg.A")
|
||||
@ -1331,7 +1258,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testConflict70(Path base) throws Exception {
|
||||
public void testNegativeInlineTag_AttributeConflict70(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
new ClassBuilder(tb, "pkg.A")
|
||||
@ -1351,7 +1278,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testConflict80(Path base) throws Exception {
|
||||
public void testNegativeInlineTag_AttributeConflict80(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
new ClassBuilder(tb, "pkg.A")
|
||||
@ -1375,7 +1302,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testConflict90(Path base) throws Exception {
|
||||
public void testNegativeInlineTag_AttributeConflict90(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
new ClassBuilder(tb, "pkg.A")
|
||||
@ -1399,7 +1326,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testErrorPositionResolution(Path base) throws Exception {
|
||||
public void testNegativeTag_PositionResolution(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
new ClassBuilder(tb, "pkg.A")
|
||||
@ -1427,7 +1354,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testRegion(Path base) throws Exception {
|
||||
public void testPositiveInlineTag_AttributeConflictRegion(Path base) throws Exception {
|
||||
record TestCase(Snippet snippet, String expectedOutput) { }
|
||||
final var testCases = List.of(
|
||||
new TestCase(newSnippetBuilder()
|
||||
@ -1605,11 +1532,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
"""
|
||||
<span class="element-name">case%s</span>()</div>
|
||||
<div class="block">
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySni\
|
||||
ppet(this)"><span data-copied="Copied!">Copy</span><img src="../copy.svg" al\
|
||||
t="Copy"></button>
|
||||
<pre class="snippet"><code>%s</code></pre>
|
||||
</div>""".formatted(index, t.expectedOutput()));
|
||||
%s""".formatted(index, getSnippetHtmlRepresentation("pkg/A.html", t.expectedOutput())));
|
||||
});
|
||||
}
|
||||
|
||||
@ -1647,7 +1570,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testAttributeValueSyntaxUnquotedCurly(Path base) throws Exception {
|
||||
public void testNegativeInlineTagMarkup_AttributeValueSyntaxUnquotedCurly(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
/*
|
||||
@ -1681,7 +1604,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testAttributeValueSyntaxCurly(Path base) throws Exception {
|
||||
public void testPositiveInlineTagMarkup_SyntaxCurly(Path base) throws Exception {
|
||||
/*
|
||||
* The snippet has to be external, otherwise its content would
|
||||
* interfere with the test: that internal closing curly would
|
||||
@ -1722,24 +1645,16 @@ public class TestSnippetTag extends JavadocTester {
|
||||
"""
|
||||
<span class="element-name">case0</span>()</div>
|
||||
<div class="block">
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySnippet\
|
||||
(this)"><span data-copied="Copied!">Copy</span><img src="../copy.svg" alt="Copy"\
|
||||
></button>
|
||||
<pre class="snippet"><code></code></pre>
|
||||
</div>""");
|
||||
""" + getSnippetHtmlRepresentation("pkg/A.html", ""));
|
||||
checkOutput("pkg/A.html", true,
|
||||
"""
|
||||
<span class="element-name">case1</span>()</div>
|
||||
<div class="block">
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySnippet\
|
||||
(this)"><span data-copied="Copied!">Copy</span><img src="../copy.svg" alt="Copy"\
|
||||
></button>
|
||||
<pre class="snippet"><code></code></pre>
|
||||
</div>""");
|
||||
""" + getSnippetHtmlRepresentation("pkg/A.html", ""));
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testAttributeValueSyntax(Path base) throws Exception {
|
||||
@Test // TODO: use combinatorial methods
|
||||
public void testPositiveExternalTagMarkup_AttributeValueSyntax(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
// Test most expected use cases for external snippet
|
||||
@ -1832,17 +1747,13 @@ public class TestSnippetTag extends JavadocTester {
|
||||
"""
|
||||
<span class="element-name">case%s</span>()</div>
|
||||
<div class="block">
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySni\
|
||||
ppet(this)"><span data-copied="Copied!">Copy</span><img src="../copy.svg" al\
|
||||
t="Copy"></button>
|
||||
<pre class="snippet"><code>2</code></pre>
|
||||
</div>
|
||||
""".formatted(j));
|
||||
%s
|
||||
""".formatted(j, getSnippetHtmlRepresentation("pkg/A.html", "2")));
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testComment(Path base) throws Exception {
|
||||
public void testPositiveInlineTagMarkup_Comment(Path base) throws Exception {
|
||||
record TestCase(Snippet snippet, String expectedOutput) { }
|
||||
final var testCases = List.of(
|
||||
new TestCase(newSnippetBuilder()
|
||||
@ -1916,16 +1827,12 @@ public class TestSnippetTag extends JavadocTester {
|
||||
"""
|
||||
<span class="element-name">case%s</span>()</div>
|
||||
<div class="block">
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySni\
|
||||
ppet(this)"><span data-copied="Copied!">Copy</span><img src="../copy.svg" al\
|
||||
t="Copy"></button>
|
||||
<pre class="snippet"><code>%s</code></pre>
|
||||
</div>""".formatted(index, t.expectedOutput()));
|
||||
%s""".formatted(index, getSnippetHtmlRepresentation("pkg/A.html", t.expectedOutput())));
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testRedundantFileNotFound(Path base) throws Exception {
|
||||
public void testNegativeHybridTag_FileNotFound(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var fileName = "text.txt";
|
||||
@ -1950,7 +1857,110 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testRedundantRegionNotFound(Path base) throws Exception {
|
||||
public void testNegativeTag_ValuelessAttributes(Path base) throws IOException {
|
||||
// none of these attributes should ever be valueless
|
||||
record TestCase(String input, String expectedError) { }
|
||||
var testCases = new ArrayList<TestCase>();
|
||||
for (String attrName : List.of("class", "file", "id", "lang", "region")) {
|
||||
// special case: valueless region attribute
|
||||
TestCase t = new TestCase("""
|
||||
{@snippet %s:
|
||||
First line
|
||||
Second line
|
||||
}
|
||||
""".formatted(attrName),
|
||||
"""
|
||||
: error: missing value for attribute "%s"
|
||||
{@snippet %s:
|
||||
^""".formatted(attrName, attrName));
|
||||
testCases.add(t);
|
||||
}
|
||||
|
||||
List<String> inputs = testCases.stream().map(s -> s.input).toList();
|
||||
StringBuilder methods = new StringBuilder();
|
||||
forEachNumbered(inputs, (i, n) -> {
|
||||
methods.append(
|
||||
"""
|
||||
|
||||
/**
|
||||
%s*/
|
||||
public void case%s() {}
|
||||
""".formatted(i, n));
|
||||
});
|
||||
|
||||
String classString =
|
||||
"""
|
||||
public class A {
|
||||
%s
|
||||
}
|
||||
""".formatted(methods.toString());
|
||||
|
||||
Path src = Files.createDirectories(base.resolve("src"));
|
||||
tb.writeJavaFiles(src, classString);
|
||||
|
||||
javadoc("-d", base.resolve("out").toString(),
|
||||
"-sourcepath", src.toString(),
|
||||
src.resolve("A.java").toString());
|
||||
checkExit(Exit.ERROR);
|
||||
// use the facility from JDK-8273154 when it becomes available
|
||||
checkOutput(Output.OUT, true, testCases.stream().map(TestCase::expectedError).toArray(String[]::new));
|
||||
checkNoCrashes();
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testNegativeTag_BlankRegion(Path base) throws Exception {
|
||||
// If a blank region were allowed, it could not be used without quotes
|
||||
record TestCase(String input, String expectedError) { }
|
||||
|
||||
var testCases = new ArrayList<TestCase>();
|
||||
for (String quote : List.of("", "'", "\""))
|
||||
for (String value : List.of("", " ")) {
|
||||
var t = new TestCase("""
|
||||
{@snippet region=%s%s%s:
|
||||
First line
|
||||
Second line
|
||||
}
|
||||
""".formatted(quote, value, quote),
|
||||
"""
|
||||
: error: illegal value for attribute "region": "%s"
|
||||
{@snippet region=%s%s%s:
|
||||
^""".formatted(quote.isEmpty() ? "" : value, quote, value, quote)); // unquoted whitespace translates to empty string
|
||||
testCases.add(t);
|
||||
}
|
||||
|
||||
List<String> inputs = testCases.stream().map(s -> s.input).toList();
|
||||
StringBuilder methods = new StringBuilder();
|
||||
forEachNumbered(inputs, (i, n) -> {
|
||||
methods.append(
|
||||
"""
|
||||
|
||||
/**
|
||||
%s*/
|
||||
public void case%s() {}
|
||||
""".formatted(i, n));
|
||||
});
|
||||
|
||||
String classString =
|
||||
"""
|
||||
public class A {
|
||||
%s
|
||||
}
|
||||
""".formatted(methods.toString());
|
||||
|
||||
Path src = Files.createDirectories(base.resolve("src"));
|
||||
tb.writeJavaFiles(src, classString);
|
||||
|
||||
javadoc("-d", base.resolve("out").toString(),
|
||||
"-sourcepath", src.toString(),
|
||||
src.resolve("A.java").toString());
|
||||
checkExit(Exit.ERROR);
|
||||
// use the facility from JDK-8273154 when it becomes available
|
||||
checkOutput(Output.OUT, true, testCases.stream().map(TestCase::expectedError).toArray(String[]::new));
|
||||
checkNoCrashes();
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testNegativeHybridTagMarkup_RegionNotFound(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var fileName = "text.txt";
|
||||
@ -1981,7 +1991,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testRedundantMismatch(Path base) throws Exception {
|
||||
public void testNegativeHybridTag_Mismatch(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var fileName = "text.txt";
|
||||
@ -2010,7 +2020,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testRedundantRegionRegionMismatch(Path base) throws Exception {
|
||||
public void testNegativeHybridTagMarkup_RegionRegionMismatch(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var fileName = "text.txt";
|
||||
@ -2050,7 +2060,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testRedundantRegion1Mismatch(Path base) throws Exception {
|
||||
public void testNegativeHybridTagMarkup_Region1Mismatch(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var fileName = "text.txt";
|
||||
@ -2084,7 +2094,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testRedundantRegion2Mismatch(Path base) throws Exception {
|
||||
public void testNegativeHybridTagMarkup_Region2Mismatch(Path base) throws Exception {
|
||||
Path srcDir = base.resolve("src");
|
||||
Path outDir = base.resolve("out");
|
||||
var fileName = "text.txt";
|
||||
@ -2121,7 +2131,7 @@ public class TestSnippetTag extends JavadocTester {
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testRedundant(Path base) throws Exception {
|
||||
public void testPositiveHybridTagMarkup(Path base) throws Exception {
|
||||
record TestCase(Snippet snippet, String expectedOutput) { }
|
||||
final var testCases = List.of(
|
||||
new TestCase(newSnippetBuilder()
|
||||
@ -2248,16 +2258,12 @@ public class TestSnippetTag extends JavadocTester {
|
||||
"""
|
||||
<span class="element-name">case%s</span>()</div>
|
||||
<div class="block">
|
||||
<div class="snippet-container"><button class="snippet-copy" onclick="copySni\
|
||||
ppet(this)"><span data-copied="Copied!">Copy</span><img src="../copy.svg" al\
|
||||
t="Copy"></button>
|
||||
<pre class="snippet"><code>%s</code></pre>
|
||||
</div>""".formatted(index, t.expectedOutput()));
|
||||
%s""".formatted(index, getSnippetHtmlRepresentation("pkg/A.html", t.expectedOutput())));
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testInvalidRegexDiagnostics(Path base) throws Exception {
|
||||
public void testNegativeInlineTagMarkup_InvalidRegexDiagnostics(Path base) throws Exception {
|
||||
|
||||
record TestCase(String input, String expectedError) { }
|
||||
|
||||
@ -2341,7 +2347,7 @@ hello there // @highlight type="italics" regex =" ["
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testErrorMessages(Path base) throws Exception {
|
||||
public void testNegativeInlineTagMarkup_ErrorMessages(Path base) throws Exception {
|
||||
|
||||
record TestCase(String input, String expectedError) { }
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user