Move JavaDoc validation to Checkstyle (#10527)

Signed-off-by: Jakub Scholz <www@scholzj.com>
strimzi · Sep 3, 2024 · e6a9450 · e6a9450
1 parent 36f1109
commit e6a9450
Show file tree

Hide file tree

Showing 8 changed files with 57 additions and 18 deletions.
diff --git 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
@@ -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>
diff --git 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/...er-operator/src/main/java/io/strimzi/operator/cluster/model/KafkaMirrorMaker2Cluster.java b/...er-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/...perator/src/main/java/io/strimzi/operator/cluster/operator/assembly/AbstractOperator.java b/...perator/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
@@ -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
@@ -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/...erator/src/main/java/io/strimzi/operator/topic/cruisecontrol/CruiseControlClientImpl.java b/...erator/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) {