> void testComparable(T o, T smaller, T equal,
T greater)
{
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsCheck.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsCheck.java
index f26a3a6c5..4777b7cb0 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsCheck.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsCheck.java
@@ -4,16 +4,25 @@
/**
* Helper class to check the operating system this Java VM runs in.
- *
+ *
* please keep the notes below as a pseudo-license:
- *
+ *
+ *
* http://stackoverflow.com/questions/228477/how-do-i-programmatically-determine-operating-system-in-java
- * compare to
- * http://svn.terracotta.org/svn/tc/dso/tags/2.6.4/code/base/common/src/com/tc/util/runtime/Os.java
- * http://www.docjar.com/html/api/org/apache/commons/lang/SystemUtils.java.html
+ *
+ *
+ * compare to:
+ *
+ *
+ * - http://svn.terracotta.org/svn/tc/dso/tags/2.6.4/code/base/common/src/com/tc/util/runtime/Os.java
+ * - http://www.docjar.com/html/api/org/apache/commons/lang/SystemUtils.java.html
+ *
*/
public class OsCheck
{
+ /**
+ * Create a new instance of the operating system check.
+ */
public OsCheck()
{
// Default constructor to fix compiler warning "missing-explicit-ctor"
@@ -41,15 +50,15 @@ public OSType getOperatingSystemType()
private static OSType detectOperatingSystemType()
{
final String os = System.getProperty("os.name", "generic").toLowerCase(Locale.ENGLISH);
- if ((os.indexOf("mac") >= 0) || (os.indexOf("darwin") >= 0))
+ if (os.contains("mac") || os.contains("darwin"))
{
return OSType.MACOS;
}
- else if (os.indexOf("win") >= 0)
+ else if (os.contains("win"))
{
return OSType.WINDOWS;
}
- else if (os.indexOf("linux") >= 0)
+ else if (os.contains("linux"))
{
return OSType.LINUX;
}
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsDetector.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsDetector.java
index 6507e4e26..e816d56f0 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsDetector.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsDetector.java
@@ -5,6 +5,10 @@
import org.itsallcode.openfasttrace.testutil.OsCheck.OSType;
+/**
+ * Helper class to detect the operating system. Contains assumption methods for
+ * JUnit.
+ */
public class OsDetector
{
private static final OsCheck OS_CHECK = new OsCheck();
@@ -14,21 +18,41 @@ private OsDetector()
// not instantiable
}
+ /**
+ * Assumes that the current operating system is Windows. If the application
+ * is not running on Windows, the assumption will fail, and the test will be
+ * aborted.
+ */
public static void assumeRunningOnWindows()
{
assumeTrue(OsDetector::runningOnWindows, "not running on windows");
}
+ /**
+ * Assumes that the current operating system is Unix-like OS. If the
+ * application is not running on a Unix-like OS, the assumption will fail,
+ * and the test will be aborted.
+ */
public static void assumeRunningOnUnix()
{
assumeFalse(OsDetector::runningOnWindows, "not running on unix");
}
+ /**
+ * Assumes that the current operating system is Linux. If the application
+ * is not running on Linux, the assumption will fail, and the test will be
+ * aborted.
+ */
public static void assumeRunningOnLinux()
{
assumeTrue(OsDetector::runningOnLinux, "not running on linux");
}
+ /**
+ * Assumes that the current operating system is macOS. If the application
+ * is not running on macOS, the assumption will fail, and the test will be
+ * aborted.
+ */
public static void assumeRunningOnMacOs()
{
assumeTrue(OsDetector::runningOnMac, "not running on macOS");
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/TestAssumptions.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/TestAssumptions.java
index 415d85977..b6ca95cf2 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/TestAssumptions.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/TestAssumptions.java
@@ -6,7 +6,7 @@
import org.opentest4j.TestAbortedException;
/**
- * Assumptions for unit and integration tests, see {@link TestAbortedException}.
+ * Assumptions for unit and integration tests.
*/
public class TestAssumptions
{
@@ -16,12 +16,11 @@ private TestAssumptions()
}
/**
- * This ensures that the current JDK supports using the
- * {@link SecurityManager}. Starting with Java 19 the security manager is
- * not supported any more.
+ * This ensures that the current JDK supports using Java's security manager.
+ * Starting with Java 19, the security manager is not supported anymore.
*
* @throws TestAbortedException
- * if the JVM does not support {@link SecurityManager}.
+ * if the JVM does not support Java's security manager.
*/
public static void assumeSecurityManagerSupported() throws TestAbortedException
{
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/cli/FakeDirectoryService.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/cli/FakeDirectoryService.java
index e9534bc0f..f57a3ef9a 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/cli/FakeDirectoryService.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/cli/FakeDirectoryService.java
@@ -2,15 +2,36 @@
import org.itsallcode.openfasttrace.api.cli.DirectoryService;
+/**
+ * A fake implementation of {@link DirectoryService} that returns a predefined
+ * directory path.
+ *
+ * Normally, the directory service provides the current directory path. This
+ * fake implementation can be used in tests to inject a predefined directory
+ * path.
+ *
+ */
public class FakeDirectoryService implements DirectoryService
{
private final String fakeCurrentDir;
+ /**
+ * Create a new {@link FakeDirectoryService} that returns a predefined
+ * directory path.
+ *
+ * @param fakeCurrentDir
+ * the directory path to be returned by {@link #getCurrent()}
+ */
public FakeDirectoryService(final String fakeCurrentDir)
{
this.fakeCurrentDir = fakeCurrentDir;
}
+ /**
+ * Get the predefined current directory path.
+ *
+ * @return the predefined directory path
+ */
@Override
public String getCurrent()
{
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/core/SampleArtifactTypes.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/core/SampleArtifactTypes.java
index 6a675f7ad..789eeb22e 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/core/SampleArtifactTypes.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/core/SampleArtifactTypes.java
@@ -1,5 +1,8 @@
package org.itsallcode.openfasttrace.testutil.core;
+/**
+ * Constants for sample artifact types used in tests.
+ */
public class SampleArtifactTypes
{
private SampleArtifactTypes()
@@ -7,12 +10,20 @@ private SampleArtifactTypes()
// Not instantiable
}
+ /** Architecture artifact type. */
public static final String ARCH = "arch";
+ /** Design artifact type. */
public static final String DSN = "dsn";
+ /** Implementation artifact type. */
public static final String IMPL = "impl";
+ /** Integration test artifact type. */
public static final String ITEST = "itest";
+ /** Operator manual artifact type. */
public static final String OMAN = "oman";
+ /** Requirement artifact type. */
public static final String REQ = "req";
+ /** Unit test artifact type. */
public static final String UTEST = "utest";
+ /** User manual artifact type. */
public static final String UMAN = "uman";
}
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/core/TraceAssertions.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/core/TraceAssertions.java
index 0e1378902..b0474b876 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/core/TraceAssertions.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/core/TraceAssertions.java
@@ -9,6 +9,9 @@
import org.itsallcode.openfasttrace.api.core.SpecificationItemId;
import org.itsallcode.openfasttrace.api.core.Trace;
+/**
+ * Provides assertion methods for testing {@link Trace} objects.
+ */
public final class TraceAssertions
{
private TraceAssertions()
@@ -16,6 +19,17 @@ private TraceAssertions()
// prevent instantiation
}
+ /**
+ * Get a linked specification item from a trace by its ID.
+ *
+ * @param trace
+ * the trace to search in
+ * @param id
+ * the ID of the item to find
+ * @return the linked specification item with the given ID
+ * @throws AssertionError
+ * if no item with the given ID is found in the trace
+ */
public static LinkedSpecificationItem getItemFromTraceForId(final Trace trace,
final SpecificationItemId id)
{
@@ -30,29 +44,63 @@ public static LinkedSpecificationItem getItemFromTraceForId(final Trace trace,
"Could not find linked specification item with ID \"" + id.toString() + "\"");
}
+ /**
+ * Assert that a trace contains the expected number of items.
+ *
+ * @param trace
+ * the trace to check
+ * @param traceSize
+ * the expected number of items
+ */
public static void assertTraceSize(final Trace trace, final int traceSize)
{
assertThat("Number of items", trace.getItems().size(), equalTo(traceSize));
}
+ /**
+ * Assert that a trace contains no defect IDs.
+ *
+ * @param trace
+ * the trace to check
+ */
public static void assertTraceContainsNoDefectIds(final Trace trace)
{
assertThat("Defect IDs in trace", trace.getDefectIds(), empty());
}
+ /**
+ * Assert that a trace contains the expected defect IDs.
+ *
+ * @param trace
+ * the trace to check
+ * @param ids
+ * the expected defect IDs
+ */
public static void assertTraceContainsDefectIds(final Trace trace,
final SpecificationItemId... ids)
{
assertThat("Defect IDs in trace", trace.getDefectIds(), contains(ids));
}
+ /**
+ * Assert that a trace has no defects.
+ *
+ * @param trace
+ * the trace to check
+ */
public static void assertTraceHasNoDefects(final Trace trace)
{
assertThat("Has no defects", trace.hasNoDefects(), equalTo(true));
}
+ /**
+ * Assert that a trace has defects.
+ *
+ * @param trace
+ * the trace to check
+ */
public static void assertTraceHasDefects(final Trace trace)
{
assertThat("Has no defects", trace.hasNoDefects(), equalTo(false));
}
-}
\ No newline at end of file
+}
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImportAssertions.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImportAssertions.java
index a8244e751..5d4180c0f 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImportAssertions.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImportAssertions.java
@@ -14,6 +14,9 @@
import org.itsallcode.openfasttrace.api.importer.input.InputFile;
import org.itsallcode.openfasttrace.testutil.importer.input.StreamInput;
+/**
+ * Provides assertion methods for testing importers.
+ */
public final class ImportAssertions
{
private static final Logger LOGGER = Logger.getLogger(ImportAssertions.class.getName());
@@ -40,6 +43,17 @@ public static void assertImportWithFactory(final Path path, final String input,
assertThat(runImporterOnText(path, input, importerFactory), matcher);
}
+ /**
+ * Run an importer on the given text and return the imported specification items.
+ *
+ * @param path
+ * path to use for the input file
+ * @param text
+ * text to import
+ * @param importerFactory
+ * factory to create the importer
+ * @return list of imported specification items
+ */
public static List runImporterOnText(final Path path, final String text,
final ImporterFactory importerFactory)
{
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImporterFactoryTestBase.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImporterFactoryTestBase.java
index 04ae9a74a..8653a0da1 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImporterFactoryTestBase.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImporterFactoryTestBase.java
@@ -27,9 +27,15 @@
@ExtendWith(MockitoExtension.class)
public abstract class ImporterFactoryTestBase
{
+ /**
+ * Mock of the importer context used in tests.
+ */
@Mock
protected ImporterContext contextMock;
+ /**
+ * Create a new instance of the test base.
+ */
protected ImporterFactoryTestBase()
{
// Default constructor to fix compiler warning "missing-explicit-ctor"
@@ -98,9 +104,24 @@ private void assertSupported(final List filenames, final boolean expecte
}
}
+ /**
+ * Create a new instance of the factory under test.
+ *
+ * @return a new instance of the factory
+ */
protected abstract T createFactory();
+ /**
+ * Get a list of filenames that should be supported by the factory.
+ *
+ * @return list of supported filenames
+ */
protected abstract List getSupportedFilenames();
+ /**
+ * Get a list of filenames that should not be supported by the factory.
+ *
+ * @return list of unsupported filenames
+ */
protected abstract List getUnsupportedFilenames();
}
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/input/StreamInput.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/input/StreamInput.java
index fce720643..963e6e2a3 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/input/StreamInput.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/input/StreamInput.java
@@ -6,6 +6,10 @@
import org.itsallcode.openfasttrace.api.importer.input.InputFile;
+/**
+ * An implementation of {@link InputFile} that reads from a
+ * {@link BufferedReader}. This is useful for tests to avoid using real files.
+ */
public class StreamInput implements InputFile
{
private final Path path;
@@ -24,7 +28,7 @@ private StreamInput(final Path path, final BufferedReader reader)
* @param path
* a dummy path.
* @param content
- * the file content.
+ * file content.
* @return an {@link InputFile}.
*/
public static InputFile forContent(final Path path, final String content)
@@ -37,9 +41,9 @@ public static InputFile forContent(final Path path, final String content)
* for tests to avoid using real files.
*
* @param path
- * a dummy path.
+ * a dummy path
* @param reader
- * the base reader.
+ * base reader
* @return an {@link InputFile}.
*/
public static InputFile forReader(final Path path, final BufferedReader reader)
@@ -47,30 +51,58 @@ public static InputFile forReader(final Path path, final BufferedReader reader)
return new StreamInput(path, reader);
}
+ /**
+ * Creates a reader for the input file.
+ *
+ * @return the reader for the input file
+ */
@Override
public BufferedReader createReader()
{
return this.reader;
}
+ /**
+ * Gets the path of the input file.
+ *
+ * @return the path of the input file as a string
+ */
@Override
public String getPath()
{
return this.path.toString();
}
+ /**
+ * Returns a string representation of this input file.
+ *
+ * @return the path of the input file
+ */
@Override
public String toString()
{
return getPath();
}
+ /**
+ * Checks if this input file is a real file on the file system.
+ *
+ * @return {@code false} since this is a stream-based input
+ */
@Override
public boolean isRealFile()
{
return false;
}
+ /**
+ * Converts this input file to a {@link Path}.
+ *
+ * @return never returns
+ * @throws UnsupportedOperationException
+ * always thrown since this operation is not supported for
+ * stream-based input
+ */
@Override
public Path toPath()
{
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/lightweightmarkup/AbstractLightWeightMarkupImporterTest.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/lightweightmarkup/AbstractLightWeightMarkupImporterTest.java
index c0fea3ac2..586de360d 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/lightweightmarkup/AbstractLightWeightMarkupImporterTest.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/lightweightmarkup/AbstractLightWeightMarkupImporterTest.java
@@ -20,6 +20,9 @@
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.*;
+/**
+ * Base class for testing lightweight markup importers.
+ */
public abstract class AbstractLightWeightMarkupImporterTest
{
private static final Path PATH = Path.of("/a/b/c.markdown");
@@ -27,11 +30,26 @@ public abstract class AbstractLightWeightMarkupImporterTest
private static final Pattern TITLE_PLACEHOLDER = Pattern.compile("\\$\\{title\\(\"([^\"]+)\", (\\d+)\\)}");
private final int titleLocationOffset;
+ /**
+ * Creates a new instance of the test base.
+ *
+ * @param titleLocationOffset
+ * offset to add to line numbers when a title is present
+ */
protected AbstractLightWeightMarkupImporterTest(final int titleLocationOffset)
{
this.titleLocationOffset = titleLocationOffset;
}
+ /**
+ * Format a title in the markup language.
+ *
+ * @param title
+ * title text
+ * @param level
+ * heading level
+ * @return formatted title
+ */
protected abstract String formatTitle(final String title, int level);
// [utest -> dsn~md.specification-item-id-format~3]
@@ -50,12 +68,32 @@ void testRequirementIdDetected(final String markdownId, final String expectedArt
.build()));
}
+ /**
+ * Assert that importing the given input produces specification items that match the given matcher.
+ *
+ * @param path
+ * path to use for the input file
+ * @param input
+ * input text to import
+ * @param matcher
+ * matcher to verify the imported specification items
+ */
protected void assertImport(final String path, final String input,
final Matcher> matcher)
{
assertImport(Path.of(path), input, matcher);
}
+ /**
+ * Assert that importing the given input produces specification items that match the given matcher.
+ *
+ * @param path
+ * path to use for the input file
+ * @param input
+ * input text to import
+ * @param matcher
+ * matcher to verify the imported specification items
+ */
protected void assertImport(final Path path, final String input,
final Matcher> matcher)
{
@@ -68,6 +106,11 @@ private String processTextInput(final String input)
.replaceAll(match -> formatTitle(match.group(1), Integer.parseInt(match.group(2))));
}
+ /**
+ * Get the importer factory for testing.
+ *
+ * @return importer factory
+ */
protected abstract ImporterFactory getImporterFactory();
// [utest -> dsn~md.requirement-references~1]
@@ -562,9 +605,9 @@ void testHeaderBelongsToNextItem()
void testParsingNeedsIgnoresExtraListItems() {
assertImport("needs_with_extra_list_items.md", """
`feat~the-feature~1`
-
+
Needs: arch
-
+
* this must not be in needs section
""",
contains(item()
@@ -579,16 +622,16 @@ void testParsingNeedsIgnoresExtraListItems() {
void testNeedsAfterCovers() {
assertImport("needs_after_covers.md", """
`dsn~needs~3`
-
+
Description with a bulleted list
-
+
* this
* that
-
+
Covers:
-
+
* `req~needs~2`
-
+
Needs: itest
""",
contains(item()
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/log/NoOpLoggingHandler.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/log/NoOpLoggingHandler.java
index b0da951d3..db4ef207a 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/log/NoOpLoggingHandler.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/log/NoOpLoggingHandler.java
@@ -1,4 +1,5 @@
package org.itsallcode.openfasttrace.testutil.log;
+
import java.util.logging.Handler;
import java.util.logging.LogRecord;
@@ -9,23 +10,38 @@
*/
public class NoOpLoggingHandler extends Handler
{
+ /**
+ * Creates a new instance of the handler.
+ */
public NoOpLoggingHandler()
{
// Default constructor to fix compiler warning "missing-explicit-ctor"
}
+ /**
+ * Ignores the log record.
+ *
+ * @param logRecord
+ * log record to ignore
+ */
@Override
public void publish(final LogRecord logRecord)
{
// empty on purpose
}
+ /**
+ * Does nothing since no logs are stored.
+ */
@Override
public void flush()
{
// empty on purpose
}
+ /**
+ * Does nothing since no resources are used.
+ */
@Override
public void close()
{
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/log/ShortClassNameFormatter.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/log/ShortClassNameFormatter.java
index 0df3b81d7..59e98a2aa 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/log/ShortClassNameFormatter.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/log/ShortClassNameFormatter.java
@@ -23,12 +23,23 @@ public final class ShortClassNameFormatter extends Formatter
{
private static final String FORMAT = "%1$tF %1$tT [%4$s] %2$s - %5$s %6$s%n";
+ /**
+ * Create a new instance of the formatter.
+ */
public ShortClassNameFormatter()
{
// Suppress warning "class ... declares no explicit constructors,
// thereby exposing a default constructor"
}
+ /**
+ * Formats the given log record as a single line with the shortened class
+ * name.
+ *
+ * @param logRecord
+ * log record to format
+ * @return formatted log record
+ */
@Override
public String format(final LogRecord logRecord)
{
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/matcher/MatcherTestBase.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/matcher/MatcherTestBase.java
index 05d7c2554..907a96a80 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/matcher/MatcherTestBase.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/matcher/MatcherTestBase.java
@@ -12,11 +12,14 @@
* This is the base class for all tests of {@link TypeSafeDiagnosingMatcher}.
*
* @param
- * the type compared by the {@link TypeSafeDiagnosingMatcher} under
+ * type compared by the {@link TypeSafeDiagnosingMatcher} under
* test.
*/
public abstract class MatcherTestBase
{
+ /**
+ * Creates a new instance of the test base.
+ */
protected MatcherTestBase()
{
// Default constructor to fix compiler warning "missing-explicit-ctor"
@@ -28,12 +31,26 @@ void testNullObject()
assertThrows(NullPointerException.class, () -> createMatcher(null));
}
+ /**
+ * Assert that the matcher matches the given object.
+ *
+ * @param object
+ * object to match
+ */
protected void assertMatch(final T object)
{
assertThat(object, createMatcher(object));
assertThat(getDescription(object), equalTo(getDescription(object)));
}
+ /**
+ * Assert that the matcher does not match different objects.
+ *
+ * @param objectA
+ * the first object
+ * @param objectB
+ * the second object
+ */
protected void assertNoMatch(final T objectA, final T objectB)
{
assertMatch(objectA);
@@ -46,6 +63,13 @@ protected void assertNoMatch(final T objectA, final T objectB)
assertThat(getDescription(objectB), equalTo(getDescription(objectB)));
}
+ /**
+ * Create a matcher for the given object.
+ *
+ * @param object
+ * object to create a matcher for
+ * @return a matcher that matches the given object
+ */
protected abstract Matcher createMatcher(final T object);
private String getDescription(final T object)
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/matcher/MultilineTextMatcher.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/matcher/MultilineTextMatcher.java
index 7243eaace..1ad593503 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/matcher/MultilineTextMatcher.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/matcher/MultilineTextMatcher.java
@@ -7,7 +7,7 @@
import org.hamcrest.TypeSafeMatcher;
/**
- * This class implements a matcher for multiline text that helps finding the
+ * This class implements a matcher for multiline text that helps find the
* differences more quickly.
*/
public class MultilineTextMatcher extends TypeSafeMatcher
@@ -16,6 +16,12 @@ public class MultilineTextMatcher extends TypeSafeMatcher
private final String originalText;
private String text;
+ /**
+ * Creates a new matcher for the given text.
+ *
+ * @param originalText
+ * text to match against
+ */
public MultilineTextMatcher(final String originalText)
{
this.originalText = originalText;
@@ -23,11 +29,11 @@ public MultilineTextMatcher(final String originalText)
/**
* Match the text against the original text.
- *
+ *
* A full match (including line separators) is required.
- *
+ *
* @param text
- * the text to be matched against the original text.
+ * text to be matched against the original text.
*/
@Override
public boolean matchesSafely(final String text)
@@ -92,7 +98,7 @@ public void describeTo(final Description description)
*
* @param lines
* lines of text
- * @return the matcher
+ * @return multiline text matcher
*/
public static MultilineTextMatcher matchesAllLines(final String... lines)
{
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/xml/IndentingXMLStreamWriter.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/xml/IndentingXMLStreamWriter.java
index 2dbc87fe7..b37e8bba6 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/xml/IndentingXMLStreamWriter.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/xml/IndentingXMLStreamWriter.java
@@ -9,7 +9,7 @@ public class IndentingXMLStreamWriter extends StreamWriterDelegate
public static final String DEFAULT_INDENT = " ";
/**
- * "\n"; the normalized representation of end-of-line in
+ * "\n"; the normalized end-of-line representation in
* XML.
*/
public static final String NORMAL_END_OF_LINE = "\n";
@@ -28,7 +28,7 @@ public class IndentingXMLStreamWriter extends StreamWriterDelegate
/** stack[depth] indicates what's been written into the current scope. */
private int[] stack = new int[] { 0, 0, 0, 0 }; // nothing written yet
- /** newLine followed by copies of indent. */
+ /** Prefix that defines how deeply a line is indented. */
private char[] linePrefix = null;
public IndentingXMLStreamWriter(final XMLStreamWriter out)
@@ -203,9 +203,9 @@ public void writeEndDocument() throws XMLStreamException
}
/**
- * Prepare to write markup, by writing a new line and indentation.
+ * Prepare to write markup by writing a new line and indentation.
*
- * @throws XMLStreamException
+ * @throws XMLStreamException here for interface compatibility only
*/
protected void beforeMarkup() throws XMLStreamException
{
@@ -214,7 +214,7 @@ protected void beforeMarkup() throws XMLStreamException
&& (this.depth > 0 || soFar != 0)) // not the first line
{
writeNewLine(this.depth);
- if (this.depth > 0 && this.indent.length() > 0)
+ if (this.depth > 0 && !this.indent.isEmpty())
{
afterMarkup(); // indentation was written
}
@@ -234,9 +234,9 @@ protected void afterData()
}
/**
- * Prepare to start an element, by allocating stack space.
+ * Prepare to start an element by allocating stack space.
*
- * @throws XMLStreamException
+ * @throws XMLStreamException here for interface compatibility only
*/
protected void beforeStartElement() throws XMLStreamException
{
@@ -259,9 +259,9 @@ protected void afterStartElement()
}
/**
- * Prepare to end an element, by writing a new line and indentation.
+ * Prepare to end an element by writing a new line and indentation.
*
- * @throws XMLStreamException
+ * @throws XMLStreamException here for interface compatibility only
*/
protected void beforeEndElement() throws XMLStreamException
{
@@ -283,7 +283,7 @@ protected void afterEndElement()
/**
* Note that a document was ended.
*
- * @throws XMLStreamException
+ * @throws XMLStreamException here for interface compatibility only
*/
protected void afterEndDocument() throws XMLStreamException
{
diff --git a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/xml/StreamWriterDelegate.java b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/xml/StreamWriterDelegate.java
index e24324530..c1f7da2ee 100644
--- a/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/xml/StreamWriterDelegate.java
+++ b/testutil/src/main/java/org/itsallcode/openfasttrace/testutil/xml/StreamWriterDelegate.java
@@ -4,13 +4,24 @@
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;
+/**
+ * This interface allows intercepting calls to a stream writer, pre-processing
+ * them and then handing the rest of the work of to a given delegate.
+ */
public abstract class StreamWriterDelegate implements XMLStreamWriter
{
+ /**
+ * Creates a new instance of the delegate.
+ *
+ * @param out
+ * stream writer to delegate to
+ */
protected StreamWriterDelegate(final XMLStreamWriter out)
{
this.out = out;
}
+ /** Stream writer to delegate to. */
protected XMLStreamWriter out;
@Override