Generate a report for missing Javadoc and fail the build if not empty

gsmet · gsmet · commit 1813c5a9c775 · 2024-11-08T16:01:31.000+01:00
diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java
@@ -37,6 +37,8 @@
 import io.quarkus.annotation.processor.documentation.config.model.Extension;
 import io.quarkus.maven.config.doc.generator.Format;
 import io.quarkus.maven.config.doc.generator.Formatter;
+import io.quarkus.maven.config.doc.generator.GenerationReport;
+import io.quarkus.maven.config.doc.generator.GenerationReport.GenerationViolation;
 import io.quarkus.qute.Engine;
 import io.quarkus.qute.ReflectionValueResolver;
 import io.quarkus.qute.UserTagSectionHelper;
@@ -91,13 +93,14 @@ public void execute() throws MojoExecutionException, MojoFailureException {
 
         List<Path> targetDirectories = findTargetDirectories(resolvedScanDirectory);
 
+        GenerationReport generationReport = new GenerationReport();
         JavadocRepository javadocRepository = JavadocMerger.mergeJavadocElements(targetDirectories);
         MergedModel mergedModel = ModelMerger.mergeModel(javadocRepository, targetDirectories, true);
 
         Format normalizedFormat = Format.normalizeFormat(format);
 
         String normalizedTheme = normalizedFormat.normalizeTheme(theme);
-        Formatter formatter = Formatter.getFormatter(javadocRepository, enableEnumTooltips, normalizedFormat);
+        Formatter formatter = Formatter.getFormatter(generationReport, javadocRepository, enableEnumTooltips, normalizedFormat);
         Engine quteEngine = initializeQuteEngine(formatter, normalizedFormat, normalizedTheme);
 
         // we generate a file per extension + top level prefix
@@ -168,6 +171,21 @@ public void execute() throws MojoExecutionException, MojoFailureException {
             }
         }
 
+        if (!generationReport.getViolations().isEmpty()) {
+            StringBuilder report = new StringBuilder(
+                    "One or more errors happened during the configuration documentation generation. Here is a full report:\n\n");
+            for (Entry<String, List<GenerationViolation>> violationsEntry : generationReport.getViolations().entrySet()) {
+                report.append("- ").append(violationsEntry.getKey()).append("\n");
+                for (GenerationViolation violation : violationsEntry.getValue()) {
+                    report.append("    . ").append(violation.sourceElement()).append(" - ").append(violation.message())
+                            .append("\n");
+                }
+                report.append("\n----\n\n");
+            }
+
+            throw new IllegalStateException(report.toString());
+        }
+
         // we generate files for generated sections
         for (Entry<Extension, List<ConfigSection>> extensionConfigSectionsEntry : mergedModel.getGeneratedConfigSections()
                 .entrySet()) {
diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AbstractFormatter.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AbstractFormatter.java
@@ -15,13 +15,16 @@
 import io.quarkus.annotation.processor.documentation.config.model.JavadocFormat;
 import io.quarkus.annotation.processor.documentation.config.util.Types;
 import io.quarkus.maven.config.doc.GenerateConfigDocMojo.Context;
+import io.quarkus.maven.config.doc.generator.GenerationReport.ConfigPropertyGenerationViolation;
 
 abstract class AbstractFormatter implements Formatter {
 
+    protected final GenerationReport generationReport;
     protected final JavadocRepository javadocRepository;
     protected final boolean enableEnumTooltips;
 
-    AbstractFormatter(JavadocRepository javadocRepository, boolean enableEnumTooltips) {
+    AbstractFormatter(GenerationReport generationReport, JavadocRepository javadocRepository, boolean enableEnumTooltips) {
+        this.generationReport = generationReport;
         this.javadocRepository = javadocRepository;
         this.enableEnumTooltips = enableEnumTooltips;
     }
@@ -41,12 +44,17 @@ public String formatDescription(ConfigProperty configProperty) {
                 configProperty.getSourceElementName());
 
         if (javadocElement.isEmpty()) {
+            generationReport.addError(new ConfigPropertyGenerationViolation(configProperty.getSourceType(),
+                    configProperty.getSourceElementName(), configProperty.getSourceElementType(), "Missing Javadoc"));
             return null;
         }
 
         String description = JavadocTransformer.transform(javadocElement.get().description(), javadocElement.get().format(),
                 javadocFormat());
         if (description == null || description.isBlank()) {
+            generationReport.addError(new ConfigPropertyGenerationViolation(configProperty.getSourceType(),
+                    configProperty.getSourceElementName(), configProperty.getSourceElementType(),
+                    "Transformed Javadoc is empty"));
             return null;
         }
 
@@ -204,17 +212,20 @@ public String formatSectionTitle(ConfigSection configSection) {
                 configSection.getSourceElementName());
 
         if (javadocElement.isEmpty()) {
-            throw new IllegalStateException(
-                    "Couldn't find section title for: " + configSection.getSourceType() + "#"
-                            + configSection.getSourceElementName());
+            generationReport.addError(new ConfigPropertyGenerationViolation(configSection.getSourceType(),
+                    configSection.getSourceElementName(), configSection.getSourceElementType(), "Missing Javadoc"));
+
+            return null;
         }
 
         String javadoc = JavadocTransformer.transform(javadocElement.get().description(), javadocElement.get().format(),
                 javadocFormat());
         if (javadoc == null || javadoc.isBlank()) {
-            throw new IllegalStateException(
-                    "Couldn't find section title for: " + configSection.getSourceType() + "#"
-                            + configSection.getSourceElementName());
+            generationReport.addError(new ConfigPropertyGenerationViolation(configSection.getSourceType(),
+                    configSection.getSourceElementName(), configSection.getSourceElementType(),
+                    "Transformed Javadoc is empty"));
+
+            return null;
         }
 
         return trimFinalDot(javadoc);
diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AsciidocFormatter.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AsciidocFormatter.java
@@ -24,8 +24,8 @@ final class AsciidocFormatter extends AbstractFormatter {
     private static final Pattern ANGLE_BRACKETS_WITH_DESCRIPTION_PATTERN = Pattern.compile("<<([a-z0-9_\\-#\\.]+?),([^>]+?)>>",
             Pattern.CASE_INSENSITIVE);
 
-    AsciidocFormatter(JavadocRepository javadocRepository, boolean enableEnumTooltips) {
-        super(javadocRepository, enableEnumTooltips);
+    AsciidocFormatter(GenerationReport generationReport, JavadocRepository javadocRepository, boolean enableEnumTooltips) {
+        super(generationReport, javadocRepository, enableEnumTooltips);
     }
 
     @Override
diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/Formatter.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/Formatter.java
@@ -31,12 +31,13 @@ default String formatDescription(ConfigProperty configProperty, Extension extens
 
     String formatName(Extension extension);
 
-    static Formatter getFormatter(JavadocRepository javadocRepository, boolean enableEnumTooltips, Format format) {
+    static Formatter getFormatter(GenerationReport generationReport, JavadocRepository javadocRepository,
+            boolean enableEnumTooltips, Format format) {
         switch (format) {
             case asciidoc:
-                return new AsciidocFormatter(javadocRepository, enableEnumTooltips);
+                return new AsciidocFormatter(generationReport, javadocRepository, enableEnumTooltips);
             case markdown:
-                return new MarkdownFormatter(javadocRepository);
+                return new MarkdownFormatter(generationReport, javadocRepository);
             default:
                 throw new IllegalArgumentException("Unsupported format: " + format);
         }
diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/GenerationReport.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/GenerationReport.java
@@ -0,0 +1,39 @@
+package io.quarkus.maven.config.doc.generator;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import io.quarkus.annotation.processor.documentation.config.model.SourceElementType;
+
+public class GenerationReport {
+
+    private Map<String, List<GenerationViolation>> violations = new LinkedHashMap<>();
+
+    void addError(GenerationViolation error) {
+        this.violations.computeIfAbsent(error.sourceType(), k -> new ArrayList<>()).add(error);
+    }
+
+    public Map<String, List<GenerationViolation>> getViolations() {
+        return violations;
+    }
+
+    public record ConfigPropertyGenerationViolation(String sourceType, String sourceElement,
+            SourceElementType sourceElementType, String message) implements GenerationViolation {
+
+        @Override
+        public String sourceElement() {
+            return sourceElement + (sourceElementType == SourceElementType.METHOD ? "()" : "");
+        }
+    }
+
+    public interface GenerationViolation {
+
+        String sourceType();
+
+        String sourceElement();
+
+        String message();
+    }
+}
diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/MarkdownFormatter.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/MarkdownFormatter.java
@@ -9,8 +9,8 @@ final class MarkdownFormatter extends AbstractFormatter {
 
     private static final String MORE_INFO_ABOUT_TYPE_FORMAT = "[🛈](#%s)";
 
-    MarkdownFormatter(JavadocRepository javadocRepository) {
-        super(javadocRepository, false);
+    MarkdownFormatter(GenerationReport generationReport, JavadocRepository javadocRepository) {
+        super(generationReport, javadocRepository, false);
     }
 
     @Override

Original file line number	Diff line number	Diff line change
`@@ -24,8 +24,8 @@ final class AsciidocFormatter extends AbstractFormatter {`
`24`	`24`	`private static final Pattern ANGLE_BRACKETS_WITH_DESCRIPTION_PATTERN = Pattern.compile("<<([a-z0-9_\\-#\\.]+?),([^>]+?)>>",`
`25`	`25`	`Pattern.CASE_INSENSITIVE);`
`26`	`26`
`27`		`- AsciidocFormatter(JavadocRepository javadocRepository, boolean enableEnumTooltips) {`
`28`		`- super(javadocRepository, enableEnumTooltips);`
	`27`	`+ AsciidocFormatter(GenerationReport generationReport, JavadocRepository javadocRepository, boolean enableEnumTooltips) {`
	`28`	`+ super(generationReport, javadocRepository, enableEnumTooltips);`
`29`	`29`	`}`
`30`	`30`
`31`	`31`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -9,8 +9,8 @@ final class MarkdownFormatter extends AbstractFormatter {`
`9`	`9`
`10`	`10`	`private static final String MORE_INFO_ABOUT_TYPE_FORMAT = "[🛈](#%s)";`
`11`	`11`
`12`		`- MarkdownFormatter(JavadocRepository javadocRepository) {`
`13`		`- super(javadocRepository, false);`
	`12`	`+ MarkdownFormatter(GenerationReport generationReport, JavadocRepository javadocRepository) {`
	`13`	`+ super(generationReport, javadocRepository, false);`
`14`	`14`	`}`
`15`	`15`
`16`	`16`	`@Override`