fix(docs): propose a mapKey for generated config docs of a Map config…

… item only for config group Fixes #4700
quarkusio · Nov 4, 2019 · 9724b0a · 9724b0a
1 parent 7d01467
commit 9724b0a
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 9 deletions.
diff --git a/...cessor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java b/...cessor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java
@@ -176,18 +176,18 @@ 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 {
+                                configDocKey.setPassThroughMap(true);
                                 configDocKey.setWithinAMap(true);
                             }
                         } else {
@@ -215,6 +215,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));

diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocKey.java b/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 +
                 '}';
     }
 }
diff --git a/...processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java b/...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);
             }

diff --git a/.../src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java b/.../src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java
@@ -71,12 +71,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,