Javadoc cleanup (#1255)

* #1234: Fixed JavaDoc for Java 21 + JavaDoc verification step
* #1234: Simplify build matrix
* #1234: Javadoc in parallell

.github/workflows/ci.yml

@@ -17,7 +17,10 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-latest, windows-latest, macos-latest ]
-        java: [ 11, 17, 21, 25 ]
+        java: [ 8, 11, 17, 21, 25 ]
+        exclude:
+          - os: macos-latest
+            java: 8
     runs-on: ${{ matrix.os }}
     permissions:
       checks: write
@@ -38,13 +41,9 @@ jobs:
           report_paths: "**/target/surefire-reports/TEST*.xml"
           check_name: Unit Test Results for OpenJDK ${{ matrix.java }} on ${{ matrix.os }}
 
-  test-jdk8:
-    name: Test OpenJDK 8 on ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ ubuntu-latest, windows-latest, macos-14 ]
-    runs-on: ${{ matrix.os }}
+  test-jdk8-macos:
+    name: Test OpenJDK 8 on macos-14
+    runs-on: macos-14
     permissions:
       checks: write
     steps:
@@ -98,9 +97,26 @@ jobs:
           report_paths: "**/target/surefire-reports/TEST*.xml"
           check_name: Unit Test Results for Oracle JDK 8 with KCMS=${{ matrix.kcms }}
 
+  javadoc:
+    name: Build JavaDoc on OpenJDK ${{ matrix.java }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        java: [8, 11, 25 ] # We only need a few versions here
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          distribution: 'temurin'
+          java-version: ${{ matrix.java }}
+          java-package: jdk
+          cache: 'maven'
+      - name: Create JavaDoc
+        run: mvn --batch-mode --no-transfer-progress -DskipTests package javadoc:javadoc
+
   release:
     name: Deploy
-    needs: [ test, test-jdk8, test-oracle ]
+    needs: [ test, test-jdk8-macos, test-oracle, javadoc ]
     if: github.ref == 'refs/heads/master' # only perform on latest master
     runs-on: ubuntu-latest
     steps:

common/common-image/src/main/java/com/twelvemonkeys/image/DiffusionDither.java

@@ -47,10 +47,10 @@ import java.util.Random;
  *  |3|5|1|
  *   - - -->
  * </p>
- * <table border="1" cellpadding="4" cellspacing="0">
+ * <table border="1">
  *     <caption>Floyd-Steinberg error-diffusion weights</caption>
- *     <tr><td bgcolor="#000000">&nbsp;</td><td class="TableHeadingColor"
- *          align="center">x</td><td>7/16</td></tr>
+ *     <tr><td style="background:#000000">&nbsp;</td><td class="TableHeadingColor"
+ *          style="text-align:center">x</td><td>7/16</td></tr>
  *     <tr><td>3/16</td><td>5/16</td><td>1/16</td></tr>
  * </table>
  * <p>

common/common-image/src/main/java/com/twelvemonkeys/image/ImageUtil.java

@@ -162,7 +162,7 @@ public final class ImageUtil {
 
     /**
      * The sharpen kernel. Uses the following 3 by 3 matrix:
-     * <table border="1" cellspacing="0">
+     * <table border="1">
      *     <caption>Sharpen Kernel Matrix</caption>
      *     <tr><td>0.0</td><td>-0.3</td><td>0.0</td></tr>
      *     <tr><td>-0.3</td><td>2.2</td><td>-0.3</td></tr>
@@ -1078,7 +1078,7 @@ public final class ImageUtil {
     /**
      * Sharpens an image using a convolution matrix.
      * The sharpen kernel used, is defined by the following 3 by 3 matrix:
-     * <table border="1" cellspacing="0">
+     * <table border="1">
      *     <caption>Sharpen Kernel Matrix</caption>
      *     <tr><td>0.0</td><td>-0.3</td><td>0.0</td></tr>
      *     <tr><td>-0.3</td><td>2.2</td><td>-0.3</td></tr>
@@ -1100,7 +1100,7 @@ public final class ImageUtil {
     /**
      * Sharpens an image using a convolution matrix.
      * The sharpen kernel used, is defined by the following 3 by 3 matrix:
-     * <table border="1" cellspacing="0">
+     * <table border="1">
      *     <caption>Sharpen Kernel Matrix</caption>
      *     <tr><td>0.0</td><td>-{@code pAmount}</td><td>0.0</td></tr>
      *     <tr><td>-{@code pAmount}</td>

common/common-lang/src/main/java/com/twelvemonkeys/lang/StringUtil.java

@@ -1765,12 +1765,11 @@ public final class StringUtil {
      * expression.
      * <p>
      * An invocation of this method of the form
-     * <tt>matches(<i>str</i>, <i>regex</i>)</tt> yields exactly the
+     * {@code matches(str, regex)} yields exactly the
      * same result as the expression
      * </p>
-     * <blockquote><tt> {@link Pattern}.
-     * {@link Pattern#matches(String, CharSequence) matches}
-     * (<i>regex</i>, <i>str</i>)</tt></blockquote>
+     * <blockquote>{@link Pattern}.
+     * {@link Pattern#matches(String, CharSequence) matches(regex, str)}</blockquote>
      *
      * @param pString the string
      * @param pRegex  the regular expression to which this string is to be matched
@@ -1789,16 +1788,14 @@ public final class StringUtil {
      * regular expression with the given pReplacement.
      * <p>
      * An invocation of this method of the form
-     * <tt>
-     *     replaceFirst(<i>str</i>, <i>regex</i>, <i>repl</i>)
-     * </tt>
+     * {@code replaceFirst(str, regex, repl)}
      * yields exactly the same result as the expression:
      * </p>
-     * <blockquote><tt>
-     * {@link Pattern}.{@link Pattern#compile(String) compile}(<i>regex</i>).
-     * {@link Pattern#matcher matcher}(<i>str</i>).
-     * {@link java.util.regex.Matcher#replaceFirst replaceFirst}(<i>repl</i>)
-     * </tt></blockquote>
+     * <blockquote>
+     * {@link Pattern#compile(String) Pattern.compile(regex)}
+     * {@link Pattern#matcher .matcher(str)}
+     * {@link java.util.regex.Matcher#replaceFirst .replaceFirst(repl)}
+     * </blockquote>
      *
      * @param pString      the string
      * @param pRegex       the regular expression to which this string is to be matched
@@ -1817,14 +1814,14 @@ public final class StringUtil {
      * regular expression with the given pReplacement.
      * <p>
      * An invocation of this method of the form
-     * <tt>replaceAll(<i>str</i>, <i>pRegex</i>, <i>repl</i>)</tt>
+     * {@code replaceAll(str, pRegex, repl)}
      * yields exactly the same result as the expression
      * </p>
-     * <blockquote><tt>
-     * {@link Pattern}.{@link Pattern#compile(String) compile}(<i>pRegex</i>).
-     * {@link Pattern#matcher matcher}(<i>str</i>{@code ).
-     * {@link java.util.regex.Matcher#replaceAll replaceAll}(}<i>repl</i>{@code )}
-     * </tt></blockquote>
+     * <blockquote>
+     * {@link Pattern#compile(String) Pattern.compile(pRegex)}
+     * {@link Pattern#matcher .matcher(str)}
+     * {@link java.util.regex.Matcher#replaceAll .replaceAll(repl)}
+     * </blockquote>
      *
      * @param pString      the string
      * @param pRegex       the regular expression to which this string is to be matched
@@ -1862,12 +1859,12 @@ public final class StringUtil {
      * </p>
      * <p>
      * An invocation of this method of the form
-     * <tt>split(<i>str</i>, <i>regex</i>, <i>n</i>)</tt>
+     * {@code split(str, regex, n)}
      * yields the same result as the expression:
      * </p>
      * <blockquote>{@link Pattern}.
-     * {@link Pattern#compile(String) compile}<tt>(<i>regex</i>).
-     * {@link Pattern#split(CharSequence,int) split}(<i>str</i>, <i>n</i>)</tt>
+     * {@link Pattern#compile(String) compile(regex)}.
+     * {@link Pattern#split(CharSequence,int) split(str, n)}
      * </blockquote>
      *
      * @param pString the string