Fix missing Javadoc comments

scholzj commented 8 months ago

We normally handle Javadoc warnings (such as missing Javadoc comments) as errors. That is currently disabled in #10. But we should add the missing Javadoc comments and enable it:

[WARNING] Javadoc Warnings
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/KafkaMetricsCollector.java:32: warning: no comment
[WARNING] public KafkaMetricsCollector(PrometheusMetricsReporterConfig config) {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/KafkaMetricsCollector.java:66: warning: no comment
[WARNING] public void addMetric(KafkaMetric metric) {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/KafkaMetricsCollector.java:70: warning: no comment
[WARNING] public void removeMetric(KafkaMetric metric) {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/KafkaMetricsCollector.java:37: warning: no comment
[WARNING] public void setPrefix(String prefix) {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/KafkaPrometheusMetricsReporter.java:89: warning: no comment
[WARNING] public int getPort() {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/MetricFamilySamplesBuilder.java:25: warning: no comment
[WARNING] public MetricFamilySamplesBuilder(Collector.Type type, String help) {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:33: warning: no comment
[WARNING] public static final String ALLOWLIST_CONFIG = CONFIG_PREFIX + "allowlist";
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:34: warning: no comment
[WARNING] public static final String ALLOWLIST_CONFIG_DEFAULT = ".*";
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:35: warning: no comment
[WARNING] public static final String ALLOWLIST_CONFIG_DOC = "A comma separated list of regex Patterns to specify the metrics to collect.";
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:27: warning: no comment
[WARNING] public static final String CONFIG_PREFIX = "prometheus.metrics.reporter.";
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:29: warning: no comment
[WARNING] public static final String PORT_CONFIG = CONFIG_PREFIX + "port";
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:30: warning: no comment
[WARNING] public static final int PORT_CONFIG_DEFAULT = 8080;
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:31: warning: no comment
[WARNING] public static final String PORT_CONFIG_DOC = "The HTTP port to expose the metrics.";
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:44: warning: no comment
[WARNING] public PrometheusMetricsReporterConfig(Map<?, ?> props) {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:54: warning: no comment
[WARNING] public boolean isAllowed(String name) {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:50: warning: no comment
[WARNING] public int port() {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/PrometheusMetricsReporterConfig.java:71: warning: no comment
[WARNING] public synchronized Optional<HTTPServer> startHttpServer() {
[WARNING] ^
[WARNING] /Users/scholzj/development/strimzi-metrics-reporter/src/main/java/io/strimzi/kafka/metrics/YammerMetricsCollector.java:41: warning: no comment
[WARNING] public YammerMetricsCollector(PrometheusMetricsReporterConfig config) {
[WARNING] ^
[WARNING] 18 warnings

OwenCorrigan76 commented 7 months ago

@scholzj @mimaison Do we want to fail the build with missing JavaDoc Warnings by enabling it here in failOnWarnings by setting it to true? Should anything be refactored in the checkstyle.xml file? The JavaDocs will be added to relevant public methods etc.


        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>${maven.javadoc.version}</version>
        <executions>
          <execution>
            <id>attach-javadocs</id>
            <goals>
              <goal>jar</goal>
            </goals>
            <configuration>
              <show>public</show>
              <failOnError>true</failOnError>
              <failOnWarnings>true</failOnWarnings>
            </configuration>
          </execution>
        </executions>
      </plugin>```

scholzj commented 7 months ago

Yes, the warnings should fail the build once the existing Javadoc issues are fixed

mimaison commented 7 months ago

Fixed in #19

strimzi / metrics-reporter

Fix missing Javadoc comments #11