Merge pull request #49409 from gsmet/config-doc-escape-default-values

Config Doc - Improve default value escaping

Author: gsmet

devtools/config-doc-maven-plugin/pom.xml

@@ -117,6 +117,10 @@
             <groupId>io.quarkus.qute</groupId>
             <artifactId>qute-core</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.smallrye.config</groupId>
+            <artifactId>smallrye-config-common</artifactId>
+        </dependency>
         <dependency>
             <groupId>javax.inject</groupId>
             <artifactId>javax.inject</artifactId>

devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AbstractFormatter.java

@@ -2,6 +2,9 @@
 
 import java.text.Normalizer;
 import java.time.Duration;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map.Entry;
 import java.util.Optional;
 import java.util.stream.Collectors;
 
@@ -16,6 +19,7 @@
 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;
+import io.smallrye.config.common.utils.StringUtil;
 
 abstract class AbstractFormatter implements Formatter {
 
@@ -112,23 +116,14 @@ public String formatDefaultValue(ConfigProperty configProperty) {
             return null;
         }
 
-        if (configProperty.isEnum() && enableEnumTooltips) {
-            Optional<String> enumConstant = configProperty.getEnumAcceptedValues().values().entrySet().stream()
-                    .filter(e -> e.getValue().configValue().equals(defaultValue))
-                    .map(e -> e.getKey())
-                    .findFirst();
-
-            if (enumConstant.isPresent()) {
-                Optional<JavadocElement> javadocElement = javadocRepository.getElement(configProperty.getType(),
-                        enumConstant.get());
-
-                if (javadocElement.isPresent()) {
-                    return tooltip(defaultValue, javadocElement.get().description());
-                }
-            }
+        List<String> defaultValues;
+        if (configProperty.isList()) {
+            defaultValues = Arrays.asList(StringUtil.split(defaultValue));
+        } else {
+            defaultValues = List.of(defaultValue);
         }
 
-        return "`" + defaultValue + "`";
+        return defaultValues.stream().map(v -> formatSingleDefaultValue(configProperty, v)).collect(Collectors.joining(", "));
     }
 
     @Override
@@ -240,6 +235,26 @@ public String formatName(Extension extension) {
         return extension.name();
     }
 
+    private String formatSingleDefaultValue(ConfigProperty configProperty, String defaultValue) {
+        if (configProperty.isEnum() && enableEnumTooltips) {
+            Optional<String> enumConstant = configProperty.getEnumAcceptedValues().values().entrySet().stream()
+                    .filter(e -> e.getValue().configValue().equals(defaultValue))
+                    .map(Entry::getKey)
+                    .findFirst();
+
+            if (enumConstant.isPresent()) {
+                Optional<JavadocElement> javadocElement = javadocRepository.getElement(configProperty.getType(),
+                        enumConstant.get());
+
+                if (javadocElement.isPresent()) {
+                    return tooltip(defaultValue, javadocElement.get().description());
+                }
+            }
+        }
+
+        return escapeDefaultValue(defaultValue);
+    }
+
     private static String trimFinalDot(String javadoc) {
         if (javadoc == null || javadoc.isBlank()) {
             return null;
@@ -262,4 +277,6 @@ private static String trimFinalDot(String javadoc) {
     protected abstract String link(String href, String description);
 
     protected abstract String tooltip(String value, String javadocDescription);
+
+    protected abstract String escapeDefaultValue(String defaultValue);
 }

devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AsciidocFormatter.java

@@ -169,4 +169,9 @@ private static String getQualifiedReference(String reference, String baseGuideUr
 
         return baseGuideUrl + "#" + reference;
     }
+
+    @Override
+    protected String escapeDefaultValue(String defaultValue) {
+        return "`+++" + defaultValue + "+++`";
+    }
 }

devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/MarkdownFormatter.java

@@ -38,4 +38,9 @@ protected String tooltip(String value, String javadocDescription) {
         // we don't have tooltip support in Markdown
         return "`" + value + "`";
     }
+
+    @Override
+    protected String escapeDefaultValue(String defaultValue) {
+        return "```" + defaultValue + "```";
+    }
 }