refactoring/javadoc_for_testutils (#458)

* #431: Attempt to fix new Maven deployment.
* #431: Removed upload of reproducible artifacts. Considered automatic with new deployment plugin.
* #431: Fixed JavaDoc in testutils.

Author: redcatbear

api/src/main/java/org/itsallcode/openfasttrace/api/core/LinkedSpecificationItem.java

@@ -247,7 +247,7 @@ public List<String> getNeedsArtifactTypes()
     /**
      * Get the artifact type which are covered.
      *
-     * @return the list of covered artifact types.
+     * @return the set of covered artifact types.
      */
     public Set<String> getCoveredArtifactTypes()
     {
@@ -265,9 +265,9 @@ public Set<String> getCoveredApprovedArtifactTypes()
     }
 
     /**
-     * Get a list of all artifact types that have unwanted coverage.
+     * Get a set of all artifact types that have unwanted coverage.
      *
-     * @return list of over-covered artifact types.
+     * @return set of over-covered artifact types.
      */
     public Set<String> getOverCoveredArtifactTypes()
     {
@@ -400,9 +400,9 @@ private List<LinkedSpecificationItem> getIncomingItems()
 
     /**
      * Check if the item is defect.
-     *
-     * An item counts a defect if the following applies:
-     *
+     * <p>
+     * An item counts as a defect if the following applies:
+     * </p>
      * <pre>
      * has duplicates
      * or (not rejected

doc/changes/changes_4.2.0.md

@@ -1,4 +1,4 @@
-# OpenFastTrace 4.2.0, released 2025-06-09
+# OpenFastTrace 4.2.0, released 2025-06-13
 
 Code name: Markdown code blocks
 

pom.xml

@@ -16,9 +16,6 @@
              We use the minimal timestamp to suppress a warning by artifact:compare. -->
         <project.build.outputTimestamp>1980-01-01T00:00:02Z</project.build.outputTimestamp>
     </properties>
-    <prerequisites>
-        <maven>3.9.9</maven>
-    </prerequisites>
     <modules>
         <module>parent</module>
         <module>api</module>

testutil/pom.xml

@@ -66,14 +66,6 @@
                     </compilerArgs>
                 </configuration>
             </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-javadoc-plugin</artifactId>
-                <configuration>
-                    <!-- This module is only used in tests, so we don't need javadoc comments. -->
-                    <skip>true</skip>
-                </configuration>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-deploy-plugin</artifactId>

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/OsCheck.java

@@ -33,7 +33,14 @@ public OsCheck()
      */
     public enum OSType
     {
-        WINDOWS, MACOS, LINUX, OTHER
+        /** Windows OS */
+        WINDOWS,
+        /** macOS */
+        MACOS,
+        /** Linux */
+        LINUX,
+        /** Any other operating system */
+        OTHER
     }
 
     /**

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImportAssertions.java

@@ -35,6 +35,8 @@ private ImportAssertions()
      *            content to be imported
      * @param matcher
      *            matcher that defines expectation for imported data
+     * @param importerFactory
+     *            factory that generates the importer
      */
     public static void assertImportWithFactory(final Path path, final String input,
             final Matcher<Iterable<? extends SpecificationItem>> matcher,
@@ -44,7 +46,8 @@ public static void assertImportWithFactory(final Path path, final String input,
     }
 
     /**
-     * Run an importer on the given text and return the imported specification items.
+     * Run an importer on the given text and return the imported specification
+     * items.
      * 
      * @param path
      *            path to use for the input file

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/importer/ImporterFactoryTestBase.java

@@ -42,7 +42,7 @@ protected ImporterFactoryTestBase()
     }
 
     @BeforeEach
-    public void initMocks()
+    void initMocks()
     {
         lenient().when(this.contextMock.getImportSettings()).thenReturn(ImportSettings.createDefault());
     }

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/matcher/StringRegexpMatcher.java

@@ -9,11 +9,23 @@
  */
 public class StringRegexpMatcher extends SubstringMatcher
 {
+    /**
+     * Create a new instance of the {@link StringRegexpMatcher}.
+     *
+     * @param regexp regular expression to match against
+     */
     public StringRegexpMatcher(final String regexp)
     {
         super("contains regexp", false, regexp);
     }
 
+    /**
+     * Check if the substring matches the given value with newlines removed.
+     *
+     * @param value value to match the substring against
+     *
+     * @return {@code true} if the given value matches the substring
+     */
     protected boolean evalSubstringOf(final String value)
     {
         return Pattern.matches(this.substring, value.replace("\n", ""));

testutil/src/main/java/org/itsallcode/openfasttrace/testutil/xml/IndentingXMLStreamWriter.java

@@ -3,39 +3,29 @@
 import javax.xml.stream.XMLStreamException;
 import javax.xml.stream.XMLStreamWriter;
 
+/**
+ * A stream writer for XML that adds indentation.
+ */
 public class IndentingXMLStreamWriter extends StreamWriterDelegate
 {
-    /** Two spaces; the default indentation. */
-    public static final String DEFAULT_INDENT = "  ";
-
-    /**
-     * "\n"; the normalized end-of-line representation in
-     * <a href="http://www.w3.org/TR/xml11/#sec-line-ends">XML</a>.
-     */
-    public static final String NORMAL_END_OF_LINE = "\n";
-
     private static final int WROTE_MARKUP = 1;
-
     private static final int WROTE_DATA = 2;
-
     private final String indent;
-
     private final String newLine;
-
     /** How deeply nested the current scope is. The root element is depth 1. */
     private int depth = 0; // document scope
-
     /** stack[depth] indicates what's been written into the current scope. */
     private int[] stack = new int[] { 0, 0, 0, 0 }; // nothing written yet
-
     /** Prefix that defines how deeply a line is indented. */
     private char[] linePrefix = null;
 
-    public IndentingXMLStreamWriter(final XMLStreamWriter out)
-    {
-        this(out, DEFAULT_INDENT, NORMAL_END_OF_LINE);
-    }
-
+    /**
+     * Create a new instance of the {@link IndentingXMLStreamWriter}.
+     *
+     * @param out stream writer to output to
+     * @param indent string used as the indentation prefix
+     * @param newLine newline character (for platform-specific output)
+     */
     public IndentingXMLStreamWriter(final XMLStreamWriter out, final String indent,
             final String newLine)
     {
@@ -205,7 +195,8 @@ public void writeEndDocument() throws XMLStreamException
     /**
      * Prepare to write markup by writing a new line and indentation.
      *
-     * @throws XMLStreamException here for interface compatibility only
+     * @throws XMLStreamException
+     *             here for interface compatibility only
      */
     protected void beforeMarkup() throws XMLStreamException
     {
@@ -236,7 +227,8 @@ protected void afterData()
     /**
      * Prepare to start an element by allocating stack space.
      *
-     * @throws XMLStreamException here for interface compatibility only
+     * @throws XMLStreamException
+     *             here for interface compatibility only
      */
     protected void beforeStartElement() throws XMLStreamException
     {
@@ -261,7 +253,8 @@ protected void afterStartElement()
     /**
      * Prepare to end an element by writing a new line and indentation.
      *
-     * @throws XMLStreamException here for interface compatibility only
+     * @throws XMLStreamException
+     *             here for interface compatibility only
      */
     protected void beforeEndElement() throws XMLStreamException
     {
@@ -283,7 +276,8 @@ protected void afterEndElement()
     /**
      * Note that a document was ended.
      *
-     * @throws XMLStreamException here for interface compatibility only
+     * @throws XMLStreamException
+     *             here for interface compatibility only
      */
     protected void afterEndDocument() throws XMLStreamException
     {
@@ -295,7 +289,14 @@ protected void afterEndDocument() throws XMLStreamException
         this.stack[this.depth] = 0; // start fresh
     }
 
-    /** Write a line separator followed by indentation. */
+    /**
+     * Write an indented line.
+     * 
+     * @param indentation
+     *            indentation depth
+     * @throws XMLStreamException
+     *             if the underlying {@link XMLStreamWriter} has a problem
+     */
     protected void writeNewLine(final int indentation) throws XMLStreamException
     {
         final int newLineLength = this.newLine.length();