fix(docs): propose a mapKey for generated config docs of a Map config item only for config group

core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java

@@ -3,6 +3,7 @@
 import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.getJavaDocSiteLink;
 import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.getKnownGenericType;
 import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.hyphenate;
+import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.stringifyType;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -176,18 +177,19 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String p
                     if (!typeArguments.isEmpty()) {
                         // FIXME: this is super dodgy: we should check the type!!
                         if (typeArguments.size() == 2) {
-                            final String mapKey = String.format(NAMED_MAP_CONFIG_ITEM_FORMAT, configDocMapKey);
                             type = typeArguments.get(1).toString();
                             configGroup = configGroups.get(type);
-                            name += mapKey;
 
                             if (configGroup != null) {
                                 name += String.format(NAMED_MAP_CONFIG_ITEM_FORMAT, configDocMapKey);
                                 List<ConfigDocItem> groupConfigItems = recordConfigItemsFromConfigGroup(configPhase, name,
-                                        configGroup, configSection, true, sectionLevel);
+                                        configGroup,
+                                        configSection, true, sectionLevel);
                                 configDocItems.addAll(groupConfigItems);
                                 continue;
                             } else {
+                                type = "`" + stringifyType(declaredType) + "`";
+                                configDocKey.setPassThroughMap(true);
                                 configDocKey.setWithinAMap(true);
                             }
                         } else {
@@ -215,6 +217,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String p
                 configDocKey.setDefaultValue(defaultValue);
                 configDocKey.setOptional(optional);
                 configDocKey.setList(list);
+                configDocKey.setDocMapKey(configDocMapKey);
                 configDocKey.setConfigDoc(configDescription);
                 configDocKey.setAcceptedValues(acceptedValues);
                 configDocKey.setJavaDocSiteLink(getJavaDocSiteLink(type));

core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocKey.java

@@ -15,10 +15,12 @@ final public class ConfigDocKey implements ConfigDocElement, Comparable<ConfigDo
     private boolean withinAMap;
     private String defaultValue;
     private String javaDocSiteLink;
+    private String docMapKey;
     private ConfigPhase configPhase;
     private List<String> acceptedValues;
     private boolean optional;
     private boolean list;
+    private boolean passThroughMap;
 
     public ConfigDocKey() {
     }
@@ -137,6 +139,22 @@ public boolean isList() {
         return list;
     }
 
+    public String getDocMapKey() {
+        return docMapKey;
+    }
+
+    public void setDocMapKey(String docMapKey) {
+        this.docMapKey = docMapKey;
+    }
+
+    public boolean isPassThroughMap() {
+        return passThroughMap;
+    }
+
+    public void setPassThroughMap(boolean passThroughMap) {
+        this.passThroughMap = passThroughMap;
+    }
+
     @Override
     public void accept(Writer writer, DocFormatter docFormatter) throws IOException {
         docFormatter.format(writer, this);
@@ -155,21 +173,23 @@ public boolean equals(Object o) {
             return false;
         ConfigDocKey that = (ConfigDocKey) o;
         return withinAMap == that.withinAMap &&
+                optional == that.optional &&
+                list == that.list &&
+                passThroughMap == that.passThroughMap &&
                 Objects.equals(type, that.type) &&
                 Objects.equals(key, that.key) &&
                 Objects.equals(configDoc, that.configDoc) &&
                 Objects.equals(defaultValue, that.defaultValue) &&
                 Objects.equals(javaDocSiteLink, that.javaDocSiteLink) &&
-                optional == that.optional &&
-                list == that.list &&
+                Objects.equals(docMapKey, that.docMapKey) &&
                 configPhase == that.configPhase &&
                 Objects.equals(acceptedValues, that.acceptedValues);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(type, key, configDoc, withinAMap, defaultValue, javaDocSiteLink, configPhase, acceptedValues,
-                optional, list);
+        return Objects.hash(type, key, configDoc, withinAMap, defaultValue, javaDocSiteLink, docMapKey, configPhase,
+                acceptedValues, optional, list, passThroughMap);
     }
 
     @Override
@@ -181,10 +201,12 @@ public String toString() {
                 ", withinAMap=" + withinAMap +
                 ", defaultValue='" + defaultValue + '\'' +
                 ", javaDocSiteLink='" + javaDocSiteLink + '\'' +
+                ", docMapKey='" + docMapKey + '\'' +
                 ", configPhase=" + configPhase +
                 ", acceptedValues=" + acceptedValues +
                 ", optional=" + optional +
                 ", list=" + list +
+                ", passThroughMap=" + passThroughMap +
                 '}';
     }
 }

core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java

@@ -77,10 +77,12 @@ private void generateDocumentation(Path targetPath, String initialAnchorPrefix,
                 if (item.hasDurationInformationNote()) {
                     hasDuration = true;
                 }
+
                 if (item.hasMemoryInformationNote()) {
                     hasMemory = true;
                 }
             }
+
             if (hasDuration) {
                 writer.append(Constants.DURATION_FORMAT_NOTE);
             }

core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/DocGeneratorUtil.java

@@ -12,6 +12,7 @@
 import java.util.stream.Collectors;
 
 import javax.lang.model.type.DeclaredType;
+import javax.lang.model.type.TypeMirror;
 
 import io.quarkus.annotation.processor.Constants;
 
@@ -359,4 +360,24 @@ private static boolean mergeSectionIntoPreviousExistingConfigItems(ConfigDocSect
 
         return false;
     }
+
+    static String stringifyType(TypeMirror typeMirror) {
+        List<? extends TypeMirror> typeArguments = ((DeclaredType) typeMirror).getTypeArguments();
+        String simpleName = typeSimpleName(typeMirror);
+        if (typeArguments.isEmpty()) {
+            return simpleName;
+        } else if (typeArguments.size() == 1) {
+            return String.format("%s<%s>", simpleName, stringifyType(typeArguments.get(0)));
+        } else if (typeArguments.size() == 2) {
+            return String.format("%s<%s,%s>", simpleName, stringifyType(typeArguments.get(0)),
+                    stringifyType(typeArguments.get(1)));
+        }
+
+        return "unknown"; // we should not reach here
+    }
+
+    private static String typeSimpleName(TypeMirror typeMirror) {
+        String type = ((DeclaredType) typeMirror).asElement().toString();
+        return type.substring(1 + type.lastIndexOf(Constants.DOT));
+    }
 }

core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java

@@ -13,7 +13,6 @@ final class SummaryTableDocFormatter implements DocFormatter {
     private static final String TABLE_ROW_FORMAT = "\n\na|%s [[%s]]`link:#%s[%s]`\n\n[.description]\n--\n%s\n--|%s %s\n|%s\n";
     private static final String TABLE_SECTION_ROW_FORMAT = "\n\nh|[[%s]]link:#%s[%s]\nh|Type\nh|Default";
     private static final String TABLE_HEADER_FORMAT = "[.configuration-legend]%s\n[%s, cols=\"80,.^10,.^10\"]\n|===";
-    //    private static final String MORE_INFO_ABOUT_SECTION_FORMAT = "link:#%s[icon:plus-circle[], title=More information about %s]";
 
     private String anchorPrefix = "";
 
@@ -71,12 +70,15 @@ public void format(Writer writer, ConfigDocKey configDocKey) throws IOException
         // for documentation it will do
         String required = configDocKey.isOptional() || !defaultValue.isEmpty() ? ""
                 : "required icon:exclamation-circle[title=Configuration property is required]";
-        String anchor = anchorPrefix + getAnchor(configDocKey.getKey());
+        String key = configDocKey.getKey();
+        String configKeyAnchor = configDocKey.isPassThroughMap() ? getAnchor(key + Constants.DASH + configDocKey.getDocMapKey())
+                : getAnchor(key);
+        String anchor = anchorPrefix + configKeyAnchor;
         writer.append(String.format(TABLE_ROW_FORMAT,
                 configDocKey.getConfigPhase().getIllustration(),
                 anchor,
                 anchor,
-                configDocKey.getKey(),
+                key,
                 // make sure nobody inserts a table cell separator here
                 doc.replace("|", "\\|"),
                 typeContent, typeDetail,
@@ -85,9 +87,6 @@ public void format(Writer writer, ConfigDocKey configDocKey) throws IOException
 
     @Override
     public void format(Writer writer, ConfigDocSection configDocSection) throws IOException {
-        //        final String moreInfoAboutSection = String.format(MORE_INFO_ABOUT_SECTION_FORMAT, getAnchor(configDocSection.getName()),
-        //                configDocSection.getSectionDetailsTitle());
-        //        final String moreInfoAboutSection = configDocSection.getSectionDetailsTitle();
         String anchor = anchorPrefix + getAnchor(configDocSection.getSectionDetailsTitle());
         final String sectionRow = String.format(TABLE_SECTION_ROW_FORMAT, anchor, anchor,
                 configDocSection.getSectionDetailsTitle());

extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalBuildTimeConfig.java

@@ -2,6 +2,8 @@
 
 import java.util.Map;
 
+import io.quarkus.runtime.annotations.ConfigDocMapKey;
+import io.quarkus.runtime.annotations.ConfigDocSection;
 import io.quarkus.runtime.annotations.ConfigItem;
 import io.quarkus.runtime.annotations.ConfigPhase;
 import io.quarkus.runtime.annotations.ConfigRoot;
@@ -16,8 +18,10 @@ public class AgroalBuildTimeConfig {
     public DataSourceBuildTimeConfig defaultDataSource;
 
     /**
-     * Additional datasources.
+     * Additional named datasources.
      */
+    @ConfigDocSection
+    @ConfigDocMapKey("datasource-name")
     @ConfigItem(name = ConfigItem.PARENT)
     public Map<String, DataSourceBuildTimeConfig> namedDataSources;
 

extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalRuntimeConfig.java

@@ -20,8 +20,8 @@ public class AgroalRuntimeConfig {
     /**
      * Additional named datasources.
      */
-    @ConfigItem(name = ConfigItem.PARENT)
-    @ConfigDocMapKey("datasource-name")
     @ConfigDocSection
+    @ConfigDocMapKey("datasource-name")
+    @ConfigItem(name = ConfigItem.PARENT)
     public Map<String, DataSourceRuntimeConfig> namedDataSources;
 }