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 index 7b68c1ee47259..ba0cf3fff9f25 100644 --- 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 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> 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> 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 index c2aca8ffb55e0..340e2c12f3c02 100644 --- 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 index 007a06c89efc0..75d8b1a370ecf 100644 --- 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 index de25d1eebdb1e..742c571c2b2e6 100644 --- 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 new file mode 100644 index 0000000000000..bf3894389d95d --- /dev/null +++ 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> violations = new LinkedHashMap<>(); + + void addError(GenerationViolation error) { + this.violations.computeIfAbsent(error.sourceType(), k -> new ArrayList<>()).add(error); + } + + public Map> 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 index d5096c259317a..cc23c399d0352 100644 --- 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