From 47187603f59c07047728f5ec09e384dc5d2ca650 Mon Sep 17 00:00:00 2001 From: Manyanda Chitimbo Date: Mon, 21 Oct 2019 18:22:02 +0200 Subject: [PATCH 1/4] fix(docs): propose a mapKey for generated config docs of a Map config item only for config group Fixes #4700 --- .../generate_doc/ConfigDoItemFinder.java | 7 +++-- .../processor/generate_doc/ConfigDocKey.java | 30 ++++++++++++++++--- .../generate_doc/ConfigDocWriter.java | 2 ++ .../SummaryTableDocFormatter.java | 7 +++-- 4 files changed, 37 insertions(+), 9 deletions(-) diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java index 20d68d9350fb9..39317383305bc 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java @@ -176,18 +176,18 @@ private List 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 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 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 index f649000c743eb..72525c41f75e0 100644 --- 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 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/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java index 317aeb36d26c2..bbf117a191df6 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java +++ b/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); } diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java index b87e226ac9c4f..d01bd6f1b47a6 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java +++ b/core/processor/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, From f40b8469449e8eedf8aa2ac0de8ff3924ac0b333 Mon Sep 17 00:00:00 2001 From: Manyanda Chitimbo Date: Thu, 31 Oct 2019 13:53:36 +0100 Subject: [PATCH 2/4] refactor: remove comments --- .../processor/generate_doc/SummaryTableDocFormatter.java | 4 ---- 1 file changed, 4 deletions(-) diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java index d01bd6f1b47a6..08cf911215c4f 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java +++ b/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 = ""; @@ -88,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()); From a33cb74e26790427bbf35c785e365de8053b243e Mon Sep 17 00:00:00 2001 From: Manyanda Chitimbo Date: Fri, 1 Nov 2019 19:05:53 +0100 Subject: [PATCH 3/4] docs: display types information for pass through Map config item --- .../generate_doc/ConfigDoItemFinder.java | 2 ++ .../generate_doc/DocGeneratorUtil.java | 21 +++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java index 39317383305bc..0db6079bb6a1e 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java +++ b/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; @@ -187,6 +188,7 @@ private List recursivelyFindConfigItems(Element element, String p configDocItems.addAll(groupConfigItems); continue; } else { + type = "`" + stringifyType(declaredType) + "`"; configDocKey.setPassThroughMap(true); configDocKey.setWithinAMap(true); } diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/DocGeneratorUtil.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/DocGeneratorUtil.java index 50f5590e0dfd1..8cf060413e738 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/DocGeneratorUtil.java +++ b/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 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)); + } } From 4499400f179e79d1e641473dc133f5a33250fcbd Mon Sep 17 00:00:00 2001 From: Manyanda Chitimbo Date: Mon, 4 Nov 2019 14:19:51 +0100 Subject: [PATCH 4/4] docs: add "datasource-name" ConfigDocMapKey and a ConfigDocSection for namedDataSources in AgroalBuildTimeConfig --- .../io/quarkus/agroal/runtime/AgroalBuildTimeConfig.java | 6 +++++- .../java/io/quarkus/agroal/runtime/AgroalRuntimeConfig.java | 4 ++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalBuildTimeConfig.java b/extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalBuildTimeConfig.java index c5c22e06e0bd8..505fe89777675 100644 --- a/extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalBuildTimeConfig.java +++ b/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 namedDataSources; diff --git a/extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalRuntimeConfig.java b/extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalRuntimeConfig.java index 007c15b4581a2..551ae0821c4a5 100644 --- a/extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalRuntimeConfig.java +++ b/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 namedDataSources; }