From efc2cfe09a0952a0c6d1566a10eac41e563007ce Mon Sep 17 00:00:00 2001
From: Jakub Scholz <www@scholzj.com>
Date: Sun, 1 Sep 2024 21:13:58 +0200
Subject: [PATCH] Move JavaDoc validation to Checkstyle

Signed-off-by: Jakub Scholz <www@scholzj.com>
---
 .checkstyle/checkstyle.xml                    | 31 +++++++++++++++++++
 .checkstyle/suppressions.xml                  |  9 ++++++
 api/pom.xml                                   |  3 --
 .../model/KafkaMirrorMaker2Cluster.java       |  4 +++
 .../operator/assembly/AbstractOperator.java   |  8 +++++
 pom.xml                                       | 11 +++----
 test/pom.xml                                  |  8 -----
 .../CruiseControlClientImpl.java              |  1 +
 8 files changed, 57 insertions(+), 18 deletions(-)

diff --git a/.checkstyle/checkstyle.xml b/.checkstyle/checkstyle.xml
index aa1c7d34b37..9a9003e1879 100644
--- a/.checkstyle/checkstyle.xml
+++ b/.checkstyle/checkstyle.xml
@@ -137,6 +137,37 @@
             <property name="tokens" value="LITERAL_ASSERT"/>
         </module>
 
+        <!-- Javadocs -->
+        <module name="MissingJavadocType">
+            <!-- public types -->
+            <property name="scope" value="public" />
+        </module>
+        <module name="MissingJavadocMethod">
+            <!-- public methods -->
+            <property name="scope" value="public" />
+        </module>
+        <module name="JavadocType">
+            <!-- public types -->
+            <property name="scope" value="public" />
+        </module>
+        <module name="JavadocVariable">
+            <!-- public variables -->
+            <property name="scope" value="public" />
+        </module>
+        <module name="JavadocMethod">
+            <!-- public methods -->
+            <property name="accessModifiers" value="public" />
+        </module>
+        <module name="JavadocBlockTagLocation" />
+        <module name="JavadocContentLocation" />
+        <module name="JavadocLeadingAsteriskAlign" />
+        <module name="JavadocMissingLeadingAsterisk" />
+        <module name="JavadocMissingWhitespaceAfterAsterisk" />
+        <module name="JavadocStyle">
+            <property name="checkFirstSentence" value="false"/>
+        </module>
+        <module name="NonEmptyAtclauseDescription"/>
+
         <!-- Make the @SuppressWarnings annotations available to Checkstyle -->
         <module name="SuppressWarningsHolder" />
     </module>
diff --git a/.checkstyle/suppressions.xml b/.checkstyle/suppressions.xml
index ae3b7faf7d8..39660c83031 100644
--- a/.checkstyle/suppressions.xml
+++ b/.checkstyle/suppressions.xml
@@ -33,4 +33,13 @@
     <suppress checks="UnnecessaryParentheses"
               files="io[/\\]strimzi[/\\].*"/>
 
+    <!-- Skip Javadoc checks for tests-->
+    <suppress checks="[JavadocMethod|JavaDocType|JavaDocVariable|MissingJavadocType|MissingJavadocMethod]" files="src[/\\]test[/\\]java[/\\].*"/>
+
+    <!-- The test module is currently not ready or Javadoc checks-->
+    <suppress checks="[JavadocMethod|JavaDocType|JavaDocVariable|MissingJavadocType|MissingJavadocMethod]" files="api[/\\]src[/\\]main[/\\]java[/\\]io[/\\]strimzi[/\\].*"/>
+
+    <!-- The api module is currently not ready or Javadoc checks-->
+    <suppress checks="[JavadocMethod|JavaDocType|JavaDocVariable|MissingJavadocType|MissingJavadocMethod]" files="test[/\\]src[/\\]main[/\\]java[/\\]io[/\\]strimzi[/\\].*"/>
+
 </suppressions>
\ No newline at end of file
diff --git a/api/pom.xml b/api/pom.xml
index cd9fb7d0f77..c7d1109f02e 100644
--- a/api/pom.xml
+++ b/api/pom.xml
@@ -19,9 +19,6 @@
     <properties>
         <maven.compiler.release>11</maven.compiler.release>
 
-        <!-- No Javadocs warnings as errors here => we do not want to fail because of warnings -->
-        <javadoc.fail.on.warnings>false</javadoc.fail.on.warnings>
-
         <!-- Points to the root directory of the Strimzi project directory and can be used for fixed location to configuration files -->
         <strimziRootDirectory>${basedir}${file.separator}..</strimziRootDirectory>
     </properties>
diff --git a/cluster-operator/src/main/java/io/strimzi/operator/cluster/model/KafkaMirrorMaker2Cluster.java b/cluster-operator/src/main/java/io/strimzi/operator/cluster/model/KafkaMirrorMaker2Cluster.java
index 3f1d5aedab9..722172fbd28 100644
--- a/cluster-operator/src/main/java/io/strimzi/operator/cluster/model/KafkaMirrorMaker2Cluster.java
+++ b/cluster-operator/src/main/java/io/strimzi/operator/cluster/model/KafkaMirrorMaker2Cluster.java
@@ -158,6 +158,10 @@ private static KafkaConnectSpec buildKafkaConnectSpec(KafkaMirrorMaker2Spec spec
 
     }
 
+    /**
+     * @return  Name of the ClusterRoleBinding
+     */
+    @Override
     public String getInitContainerClusterRoleBindingName() {
         return KafkaMirrorMaker2Resources.initContainerClusterRoleBindingName(cluster, namespace);
     }
diff --git a/cluster-operator/src/main/java/io/strimzi/operator/cluster/operator/assembly/AbstractOperator.java b/cluster-operator/src/main/java/io/strimzi/operator/cluster/operator/assembly/AbstractOperator.java
index 7e9570d41b2..9e961d8b9d9 100644
--- a/cluster-operator/src/main/java/io/strimzi/operator/cluster/operator/assembly/AbstractOperator.java
+++ b/cluster-operator/src/main/java/io/strimzi/operator/cluster/operator/assembly/AbstractOperator.java
@@ -468,6 +468,14 @@ private Future<Void> releaseLockAndTimer(Reconciliation reconciliation, Lock loc
         return Future.succeededFuture();
     }
 
+    /**
+     * Find the names of all resources that should be reconciled
+     *
+     * @param namespace The namespace where the resources should be looked up
+     *
+     * @return  A future with a set of resources found in given namespace
+     */
+    @Override
     public Future<Set<NamespaceAndName>> allResourceNames(String namespace) {
         return resourceOperator.listAsync(namespace, selector())
                 .map(resourceList ->
diff --git a/pom.xml b/pom.xml
index 5c0a3208968..721cc802676 100644
--- a/pom.xml
+++ b/pom.xml
@@ -91,9 +91,6 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.release>17</maven.compiler.release>
 
-        <!-- Configures if we should fail on warnings when generating Javadocs -->
-        <javadoc.fail.on.warnings>true</javadoc.fail.on.warnings>
-
         <!-- Points to the root directory of the Strimzi project directory and can be used for fixed location to configuration files -->
         <strimziRootDirectory>${basedir}</strimziRootDirectory>
 
@@ -103,11 +100,11 @@
         <maven.failsafe.version>3.1.2</maven.failsafe.version>
         <maven.assembly.version>3.4.2</maven.assembly.version>
         <maven.shade.version>3.4.1</maven.shade.version>
-        <maven.javadoc.version>3.4.1</maven.javadoc.version>
+        <maven.javadoc.version>3.10.0</maven.javadoc.version>
         <maven.source.version>3.0.1</maven.source.version>
         <maven.dependency.version>3.3.0</maven.dependency.version>
         <maven.gpg.version>1.6</maven.gpg.version>
-        <maven.checkstyle.version>3.3.0</maven.checkstyle.version>
+        <maven.checkstyle.version>3.5.0</maven.checkstyle.version>
         <maven.enforcer.version>3.0.0-M2</maven.enforcer.version>
         <maven.jar.version>3.1.0</maven.jar.version>
         <sonatype.nexus.staging.version>1.7.0</sonatype.nexus.staging.version>
@@ -117,7 +114,7 @@
         <maven.resources.version>3.1.0</maven.resources.version>
 
         <!-- Build tools -->
-        <checkstyle.version>10.12.2</checkstyle.version>
+        <checkstyle.version>10.18.1</checkstyle.version>
         <spotbugs.version>4.7.3</spotbugs.version>
         <sundrio.version>0.200.0</sundrio.version>
         <lombok.version>1.18.32</lombok.version>
@@ -1169,7 +1166,7 @@
                             <sourcepath>${project.build.sourceDirectory}:${project.build.directory}/generated-sources/annotations</sourcepath>
                             <show>public</show>
                             <failOnError>true</failOnError>
-                            <failOnWarnings>${javadoc.fail.on.warnings}</failOnWarnings>
+                            <failOnWarnings>false</failOnWarnings>
                         </configuration>
                     </execution>
                 </executions>
diff --git a/test/pom.xml b/test/pom.xml
index 901711e73a3..7ad1fa1c1f5 100644
--- a/test/pom.xml
+++ b/test/pom.xml
@@ -107,14 +107,6 @@
 
     <build>
         <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-javadoc-plugin</artifactId>
-                <version>${maven.javadoc.version}</version>
-                <configuration>
-                    <doclint>none</doclint>
-                </configuration>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-dependency-plugin</artifactId>
diff --git a/topic-operator/src/main/java/io/strimzi/operator/topic/cruisecontrol/CruiseControlClientImpl.java b/topic-operator/src/main/java/io/strimzi/operator/topic/cruisecontrol/CruiseControlClientImpl.java
index ae904b9508c..e96cee52468 100644
--- a/topic-operator/src/main/java/io/strimzi/operator/topic/cruisecontrol/CruiseControlClientImpl.java
+++ b/topic-operator/src/main/java/io/strimzi/operator/topic/cruisecontrol/CruiseControlClientImpl.java
@@ -192,6 +192,7 @@ public UserTasksResponse userTasks(Set<String> userTaskIds) {
         }).join();
     }
 
+    @Override
     public Optional<String> errorMessage(HttpResponse<String> response) {
         if (response != null) {
             if (response.statusCode() == 401) {