Skip to content

Commit

Permalink
Merge pull request quarkusio#4715 from machi1990/fix/hide-map-key-for…
Browse files Browse the repository at this point in the history 
…-pass-through-config

fix(docs): propose a mapKey for generated config docs of a Map config item only for config group
  • Loading branch information
@gsmet
gsmet authored Nov 4, 2019
2 parents 7991f16 + 4499400 commit ff84cc2
Show file tree
Hide file tree
Showing 7 changed files with 67 additions and 16 deletions.
9 changes: 6 additions & 3 deletions ...cessor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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));
Expand Down
30 changes: 26 additions & 4 deletions core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocKey.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
}
Expand Down Expand Up @@ -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);
Expand All @@ -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
Expand All @@ -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 +
'}';
}
}
2 changes: 2 additions & 0 deletions ...processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
Expand Down
21 changes: 21 additions & 0 deletions ...rocessor/src/main/java/io/quarkus/annotation/processor/generate_doc/DocGeneratorUtil.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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));
}
}
11 changes: 5 additions & 6 deletions .../src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 = "";

Expand Down Expand Up @@ -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,
Expand All @@ -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());
Expand Down
6 changes: 5 additions & 1 deletion extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalBuildTimeConfig.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;

Expand Down
4 changes: 2 additions & 2 deletions extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/AgroalRuntimeConfig.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

0 comments on commit ff84cc2

Please sign in to comment.