Improve All Config page significantly

core/deployment/src/main/java/io/quarkus/banner/BannerConfig.java

@@ -3,6 +3,9 @@
 import io.quarkus.runtime.annotations.ConfigItem;
 import io.quarkus.runtime.annotations.ConfigRoot;
 
+/**
+ * Banner
+ */
 @ConfigRoot(name = "banner")
 public class BannerConfig {
 

core/deployment/src/main/java/io/quarkus/deployment/BootstrapConfig.java

@@ -4,6 +4,8 @@
 import io.quarkus.runtime.annotations.ConfigRoot;
 
 /**
+ * Bootstrap
+ * <p>
  * This is used currently only to suppress warnings about unknown properties
  * when the user supplies something like: -Dquarkus.debug.reflection=true
  */

core/deployment/src/main/java/io/quarkus/deployment/ConfigBuildTimeConfig.java

@@ -1,10 +1,15 @@
 package io.quarkus.deployment;
 
+import io.quarkus.runtime.annotations.ConfigDocPrefix;
 import io.quarkus.runtime.annotations.ConfigItem;
 import io.quarkus.runtime.annotations.ConfigPhase;
 import io.quarkus.runtime.annotations.ConfigRoot;
 
+/**
+ * Configuration
+ */
 @ConfigRoot(name = ConfigItem.PARENT, phase = ConfigPhase.BUILD_TIME)
+@ConfigDocPrefix("quarkus.config")
 public class ConfigBuildTimeConfig {
     /**
      * <p>

core/deployment/src/main/java/io/quarkus/deployment/DebugConfig.java

@@ -6,6 +6,8 @@
 import io.quarkus.runtime.annotations.ConfigRoot;
 
 /**
+ * Debugging
+ * <p>
  * This is used currently only to suppress warnings about unknown properties
  * when the user supplies something like: -Dquarkus.debug.reflection=true
  *

core/deployment/src/main/java/io/quarkus/deployment/JniProcessor.java

@@ -18,6 +18,9 @@ public class JniProcessor {
 
     JniConfig jni;
 
+    /**
+     * JNI
+     */
     @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
     static class JniConfig {
         /**

core/deployment/src/main/java/io/quarkus/deployment/PlatformConfig.java

@@ -4,6 +4,8 @@
 import io.quarkus.runtime.annotations.ConfigRoot;
 
 /**
+ * Platform
+ * <p>
  * This is used currently only to suppress warnings about unknown properties
  * when the user supplies something like: -Dquarkus.platform.group-id=someGroup
  *

core/deployment/src/main/java/io/quarkus/deployment/SnapStartConfig.java

@@ -7,6 +7,8 @@
 import io.quarkus.runtime.annotations.ConfigRoot;
 
 /**
+ * SnapStart
+ * <p>
  * Configure the various optimization to use
  * <a href="https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html">SnapStart</a>
  */

core/deployment/src/main/java/io/quarkus/deployment/SslProcessor.java

@@ -16,6 +16,9 @@ public class SslProcessor {
 
     SslConfig ssl;
 
+    /**
+     * SSL
+     */
     @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
     static class SslConfig {
         /**

core/deployment/src/main/java/io/quarkus/deployment/cmd/DeployConfig.java

@@ -6,6 +6,9 @@
 import io.quarkus.runtime.annotations.ConfigPhase;
 import io.quarkus.runtime.annotations.ConfigRoot;
 
+/**
+ * Deployment
+ */
 @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
 public class DeployConfig {
     /**

core/deployment/src/main/java/io/quarkus/deployment/configuration/ClassLoadingConfig.java

@@ -11,6 +11,8 @@
 import io.quarkus.runtime.annotations.ConfigRoot;
 
 /**
+ * Class loading
+ * <p>
  * WARNING: This is not normal quarkus config, this is only read from application.properties.
  * <p>
  * This is because it is needed before any of the config infrastructure is set up.

core/deployment/src/main/java/io/quarkus/deployment/configuration/tracker/ConfigTrackingConfig.java

@@ -13,6 +13,8 @@
 import io.smallrye.config.WithDefault;
 
 /**
+ * Configuration tracking and dumping
+ * <p>
  * Configuration options for application build time configuration usage tracking
  * and dumping.
  */

core/deployment/src/main/java/io/quarkus/deployment/console/ConsoleConfig.java

@@ -3,6 +3,9 @@
 import io.quarkus.runtime.annotations.ConfigItem;
 import io.quarkus.runtime.annotations.ConfigRoot;
 
+/**
+ * Console
+ */
 @ConfigRoot
 public class ConsoleConfig {
 

core/deployment/src/main/java/io/quarkus/deployment/dev/devservices/GlobalDevServicesConfig.java

@@ -7,6 +7,9 @@
 import io.quarkus.runtime.annotations.ConfigItem;
 import io.quarkus.runtime.annotations.ConfigRoot;
 
+/**
+ * Dev Services
+ */
 @ConfigRoot(name = "devservices")
 public class GlobalDevServicesConfig {
 

core/deployment/src/main/java/io/quarkus/deployment/dev/testing/TestConfig.java

@@ -11,6 +11,8 @@
 import io.quarkus.runtime.annotations.ConfigRoot;
 
 /**
+ * Testing
+ * <p>
  * This is used currently only to suppress warnings about unknown properties
  * when the user supplies something like: -Dquarkus.test.profile=someProfile or -Dquarkus.test.native-image-profile=someProfile
  * <p>

core/deployment/src/main/java/io/quarkus/deployment/ide/IdeConfig.java

@@ -3,6 +3,9 @@
 import io.quarkus.runtime.annotations.ConfigItem;
 import io.quarkus.runtime.annotations.ConfigRoot;
 
+/**
+ * IDE
+ */
 @ConfigRoot
 public class IdeConfig {
 

core/deployment/src/main/java/io/quarkus/deployment/index/ApplicationArchiveBuildStep.java

@@ -56,6 +56,9 @@ public class ApplicationArchiveBuildStep {
 
     IndexDependencyConfiguration config;
 
+    /**
+     * Indexing
+     */
     @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
     static final class IndexDependencyConfiguration {
         /**

core/deployment/src/main/java/io/quarkus/deployment/naming/NamingConfig.java

@@ -3,6 +3,9 @@
 import io.quarkus.runtime.annotations.ConfigItem;
 import io.quarkus.runtime.annotations.ConfigRoot;
 
+/**
+ * Naming
+ */
 @ConfigRoot
 public class NamingConfig {
 

core/deployment/src/main/java/io/quarkus/deployment/pkg/NativeConfig.java

@@ -17,6 +17,9 @@
 import io.smallrye.config.WithDefault;
 import io.smallrye.config.WithParentName;
 
+/**
+ * Native executables
+ */
 @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
 @ConfigMapping(prefix = "quarkus.native")
 public interface NativeConfig {

core/deployment/src/main/java/io/quarkus/deployment/pkg/PackageConfig.java

@@ -16,6 +16,8 @@
 import io.smallrye.config.WithDefault;
 
 /**
+ * Packaging the application
+ * <p>
  * Configuration relating to creating a packaged output.
  */
 @ConfigMapping(prefix = "quarkus.package")

core/deployment/src/main/java/io/quarkus/deployment/shutdown/ShutdownBuildTimeConfig.java

@@ -4,6 +4,9 @@
 import io.quarkus.runtime.annotations.ConfigPhase;
 import io.quarkus.runtime.annotations.ConfigRoot;
 
+/**
+ * Shutdown
+ */
 @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
 public class ShutdownBuildTimeConfig {
 

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/merger/JavadocRepository.java

@@ -17,4 +17,8 @@ public final class JavadocRepository {
     public Optional<JavadocElement> getElement(String className, String elementName) {
         return Optional.ofNullable(javadocElementsMap.get(className + Markers.DOT + elementName));
     }
+
+    public Optional<JavadocElement> getElement(String className) {
+        return Optional.ofNullable(javadocElementsMap.get(className));
+    }
 }

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/merger/MergedModel.java

@@ -13,21 +13,21 @@
  */
 public class MergedModel {
 
-    private final Map<Extension, Map<String, ConfigRoot>> configRoots;
+    private final Map<Extension, Map<ConfigRootKey, ConfigRoot>> configRoots;
 
     private final Map<String, ConfigRoot> configRootsInSpecificFile;
 
     private final Map<Extension, List<ConfigSection>> generatedConfigSections;
 
-    MergedModel(Map<Extension, Map<String, ConfigRoot>> configRoots,
+    MergedModel(Map<Extension, Map<ConfigRootKey, ConfigRoot>> configRoots,
             Map<String, ConfigRoot> configRootsInSpecificFile,
             Map<Extension, List<ConfigSection>> configSections) {
         this.configRoots = Collections.unmodifiableMap(configRoots);
         this.configRootsInSpecificFile = Collections.unmodifiableMap(configRootsInSpecificFile);
         this.generatedConfigSections = Collections.unmodifiableMap(configSections);
     }
 
-    public Map<Extension, Map<String, ConfigRoot>> getConfigRoots() {
+    public Map<Extension, Map<ConfigRootKey, ConfigRoot>> getConfigRoots() {
         return configRoots;
     }
 
@@ -42,4 +42,31 @@ public Map<Extension, List<ConfigSection>> getGeneratedConfigSections() {
     public boolean isEmpty() {
         return configRoots.isEmpty();
     }
+
+    public record ConfigRootKey(String topLevelPrefix, String description) implements Comparable<ConfigRootKey> {
+
+        @Override
+        public final String toString() {
+            return topLevelPrefix;
+        }
+
+        @Override
+        public int compareTo(ConfigRootKey other) {
+            int compareTopLevelPrefix = this.topLevelPrefix.compareToIgnoreCase(other.topLevelPrefix);
+            if (compareTopLevelPrefix != 0) {
+                return compareTopLevelPrefix;
+            }
+            if (this.description == null && other.description == null) {
+                return 0;
+            }
+            if (this.description == null) {
+                return -1;
+            }
+            if (other.description == null) {
+                return 1;
+            }
+
+            return this.description.compareToIgnoreCase(other.description);
+        }
+    }
 }

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/merger/ModelMerger.java

@@ -9,16 +9,19 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
+import java.util.Optional;
 import java.util.TreeMap;
 import java.util.stream.Collectors;
 
 import io.quarkus.annotation.processor.Outputs;
+import io.quarkus.annotation.processor.documentation.config.merger.MergedModel.ConfigRootKey;
 import io.quarkus.annotation.processor.documentation.config.model.AbstractConfigItem;
 import io.quarkus.annotation.processor.documentation.config.model.ConfigItemCollection;
 import io.quarkus.annotation.processor.documentation.config.model.ConfigRoot;
 import io.quarkus.annotation.processor.documentation.config.model.ConfigSection;
 import io.quarkus.annotation.processor.documentation.config.model.Extension;
 import io.quarkus.annotation.processor.documentation.config.model.Extension.NameSource;
+import io.quarkus.annotation.processor.documentation.config.model.JavadocElements.JavadocElement;
 import io.quarkus.annotation.processor.documentation.config.model.ResolvedModel;
 import io.quarkus.annotation.processor.documentation.config.util.JacksonMappers;
 
@@ -32,8 +35,16 @@ private ModelMerger() {
      * target/ directories found in the parent directory scanned).
      */
     public static MergedModel mergeModel(List<Path> buildOutputDirectories) {
+        return mergeModel(null, buildOutputDirectories);
+    }
+
+    /**
+     * Merge all the resolved models obtained from a list of build output directories (e.g. in the case of Maven, the list of
+     * target/ directories found in the parent directory scanned).
+     */
+    public static MergedModel mergeModel(JavadocRepository javadocRepository, List<Path> buildOutputDirectories) {
         // keyed on extension and then top level prefix
-        Map<Extension, Map<String, ConfigRoot>> configRoots = new HashMap<>();
+        Map<Extension, Map<ConfigRootKey, ConfigRoot>> configRoots = new HashMap<>();
         // keyed on file name
         Map<String, ConfigRoot> configRootsInSpecificFile = new TreeMap<>();
         // keyed on extension
@@ -74,13 +85,14 @@ public static MergedModel mergeModel(List<Path> buildOutputDirectories) {
                         continue;
                     }
 
-                    Map<String, ConfigRoot> extensionConfigRoots = configRoots.computeIfAbsent(configRoot.getExtension(),
-                            e -> new HashMap<>());
+                    Map<ConfigRootKey, ConfigRoot> extensionConfigRoots = configRoots.computeIfAbsent(configRoot.getExtension(),
+                            e -> new TreeMap<>());
 
-                    ConfigRoot existingConfigRoot = extensionConfigRoots.get(configRoot.getTopLevelPrefix());
+                    ConfigRootKey configRootKey = getConfigRootKey(javadocRepository, configRoot);
+                    ConfigRoot existingConfigRoot = extensionConfigRoots.get(configRootKey);
 
                     if (existingConfigRoot == null) {
-                        extensionConfigRoots.put(configRoot.getTopLevelPrefix(), configRoot);
+                        extensionConfigRoots.put(configRootKey, configRoot);
                     } else {
                         existingConfigRoot.merge(configRoot);
                     }
@@ -92,7 +104,7 @@ public static MergedModel mergeModel(List<Path> buildOutputDirectories) {
 
         configRoots = retainBestExtensionKey(configRoots);
 
-        for (Entry<Extension, Map<String, ConfigRoot>> extensionConfigRootsEntry : configRoots.entrySet()) {
+        for (Entry<Extension, Map<ConfigRootKey, ConfigRoot>> extensionConfigRootsEntry : configRoots.entrySet()) {
             List<ConfigSection> extensionGeneratedConfigSections = generatedConfigSections
                     .computeIfAbsent(extensionConfigRootsEntry.getKey(), e -> new ArrayList<>());
 
@@ -104,8 +116,8 @@ public static MergedModel mergeModel(List<Path> buildOutputDirectories) {
         return new MergedModel(configRoots, configRootsInSpecificFile, generatedConfigSections);
     }
 
-    private static Map<Extension, Map<String, ConfigRoot>> retainBestExtensionKey(
-            Map<Extension, Map<String, ConfigRoot>> configRoots) {
+    private static Map<Extension, Map<ConfigRootKey, ConfigRoot>> retainBestExtensionKey(
+            Map<Extension, Map<ConfigRootKey, ConfigRoot>> configRoots) {
         return configRoots.entrySet().stream().collect(Collectors.toMap(e -> {
             Extension extension = e.getKey();
 
@@ -138,4 +150,51 @@ private static void collectGeneratedConfigSections(List<ConfigSection> extension
             collectGeneratedConfigSections(extensionGeneratedConfigSections, configSection);
         }
     }
+
+    private static ConfigRootKey getConfigRootKey(JavadocRepository javadocRepository, ConfigRoot configRoot) {
+        return new ConfigRootKey(configRoot.getTopLevelPrefix(), getConfigRootDescription(javadocRepository, configRoot));
+    }
+
+    // here we only return a description if all the qualified names of the config root have a similar description
+    private static String getConfigRootDescription(JavadocRepository javadocRepository, ConfigRoot configRoot) {
+        if (!configRoot.getExtension().splitOnConfigRootDescription()) {
+            return null;
+        }
+        if (javadocRepository == null) {
+            return null;
+        }
+
+        String description = null;
+
+        for (String qualifiedName : configRoot.getQualifiedNames()) {
+            Optional<JavadocElement> javadocElement = javadocRepository.getElement(qualifiedName);
+
+            if (javadocElement.isEmpty()) {
+                return null;
+            }
+
+            if (description == null) {
+                description = trimFinalDot(javadocElement.get().description());
+            } else if (!description.equals(trimFinalDot(javadocElement.get().description()))) {
+                return null;
+            }
+        }
+
+        return description;
+    }
+
+    private static String trimFinalDot(String javadoc) {
+        if (javadoc == null || javadoc.isBlank()) {
+            return null;
+        }
+
+        javadoc = javadoc.trim();
+        int dotIndex = javadoc.indexOf(".");
+
+        if (dotIndex == -1) {
+            return javadoc;
+        }
+
+        return javadoc.substring(0, dotIndex);
+    }
 }