Skip to content

Commit

Permalink
Merge pull request #34514 from radcortez/with-unnamed-key-docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@gastaldi
gastaldi authored Jul 4, 2023
2 parents 609d07c + f32919f commit ac5b8d0
Show file tree
Hide file tree
Showing 5 changed files with 75 additions and 16 deletions.
1 change: 1 addition & 0 deletions core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ final public class Constants {
public static final String ANNOTATION_CONFIG_WITH_NAME = "io.smallrye.config.WithName";
public static final String ANNOTATION_CONFIG_WITH_PARENT_NAME = "io.smallrye.config.WithParentName";
public static final String ANNOTATION_CONFIG_WITH_DEFAULT = "io.smallrye.config.WithDefault";
public static final String ANNOTATION_CONFIG_WITH_UNNAMED_KEY = "io.smallrye.config.WithUnnamedKey";

public static final Set<String> SUPPORTED_ANNOTATIONS_TYPES = Set.of(ANNOTATION_BUILD_STEP, ANNOTATION_CONFIG_GROUP,
ANNOTATION_CONFIG_ROOT, ANNOTATION_RECORDER);
Expand Down
61 changes: 50 additions & 11 deletions ...essor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_WITH_DEFAULT;
import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_WITH_NAME;
import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_WITH_PARENT_NAME;
import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_WITH_UNNAMED_KEY;
import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONVERT_WITH;
import static io.quarkus.annotation.processor.Constants.ANNOTATION_DEFAULT_CONVERTER;
import static io.quarkus.annotation.processor.Constants.DOT;
Expand All @@ -22,6 +23,8 @@
import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.hyphenate;
import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.hyphenateEnumValue;
import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.stringifyType;
import static java.util.Collections.emptyList;
import static java.util.stream.Collectors.toList;
import static javax.lang.model.element.Modifier.ABSTRACT;

import java.io.IOException;
Expand Down Expand Up @@ -167,6 +170,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r

String hyphenatedFieldName = hyphenate(fieldName);
String configDocMapKey = hyphenatedFieldName;
boolean unnamedMapKey = false;
boolean isDeprecated = false;
boolean generateDocumentation = true;
ConfigDocSection configSection = new ConfigDocSection();
Expand Down Expand Up @@ -229,6 +233,8 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
defaultValueDoc = annotationMirror.getElementValues().values().iterator().next().getValue().toString();
} else if (annotationName.equals(ANNOTATION_CONFIG_WITH_DEFAULT)) {
defaultValue = annotationMirror.getElementValues().values().iterator().next().getValue().toString();
} else if (annotationName.equals(ANNOTATION_CONFIG_WITH_UNNAMED_KEY)) {
unnamedMapKey = true;
}
}

Expand All @@ -250,7 +256,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
String type = getType(typeMirror);

if (isConfigGroup(type)) {
List<ConfigDocItem> groupConfigItems = readConfigGroupItems(configPhase, rootName, name, type,
List<ConfigDocItem> groupConfigItems = readConfigGroupItems(configPhase, rootName, name, emptyList(), type,
configSection, withinAMap, generateSeparateConfigGroupDocsFiles);
DocGeneratorUtil.appendConfigItemsIntoExistingOnes(configDocItems, groupConfigItems);
} else {
Expand All @@ -273,9 +279,16 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
if (typeArguments.size() == 2) {
type = getType(typeArguments.get(1));
if (isConfigGroup(type)) {
name += String.format(NAMED_MAP_CONFIG_ITEM_FORMAT, configDocMapKey);
List<ConfigDocItem> groupConfigItems = readConfigGroupItems(configPhase, rootName, name, type,
configSection, true, generateSeparateConfigGroupDocsFiles);
List<String> additionalNames;
if (unnamedMapKey) {
additionalNames = List
.of(name + String.format(NAMED_MAP_CONFIG_ITEM_FORMAT, configDocMapKey));
} else {
name += String.format(NAMED_MAP_CONFIG_ITEM_FORMAT, configDocMapKey);
additionalNames = emptyList();
}
List<ConfigDocItem> groupConfigItems = readConfigGroupItems(configPhase, rootName, name,
additionalNames, type, configSection, true, generateSeparateConfigGroupDocsFiles);
DocGeneratorUtil.appendConfigItemsIntoExistingOnes(configDocItems, groupConfigItems);
continue;
} else {
Expand All @@ -301,7 +314,8 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
}
configSection.setOptional(true);
List<ConfigDocItem> groupConfigItems = readConfigGroupItems(configPhase, rootName, name,
typeInString, configSection, withinAMap, generateSeparateConfigGroupDocsFiles);
emptyList(), typeInString, configSection, withinAMap,
generateSeparateConfigGroupDocsFiles);
DocGeneratorUtil.appendConfigItemsIntoExistingOnes(configDocItems, groupConfigItems);
continue;
} else if ((typeInString.startsWith(List.class.getName())
Expand Down Expand Up @@ -355,6 +369,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
}

configDocKey.setKey(name);
configDocKey.setAdditionalKeys(emptyList());
configDocKey.setType(type);
configDocKey.setList(list);
configDocKey.setOptional(optional);
Expand Down Expand Up @@ -509,8 +524,15 @@ private boolean isDurationType(TypeMirror realTypeMirror) {
* configuration group if properly updated afterwards.
*
*/
private List<ConfigDocItem> readConfigGroupItems(ConfigPhase configPhase, String topLevelRootName, String parentName,
String configGroup, ConfigDocSection configSection, boolean withinAMap, boolean generateSeparateConfigGroupDocs)
private List<ConfigDocItem> readConfigGroupItems(
ConfigPhase configPhase,
String topLevelRootName,
String parentName,
List<String> additionalNames,
String configGroup,
ConfigDocSection configSection,
boolean withinAMap,
boolean generateSeparateConfigGroupDocs)
throws JsonProcessingException {

configSection.setConfigGroupType(configGroup);
Expand All @@ -534,8 +556,8 @@ private List<ConfigDocItem> readConfigGroupItems(ConfigPhase configPhase, String
allConfigurationGroups.put(configGroup, OBJECT_MAPPER.writeValueAsString(groupConfigItems));
}

groupConfigItems = decorateGroupItems(groupConfigItems, configPhase, topLevelRootName, parentName, withinAMap,
generateSeparateConfigGroupDocs);
groupConfigItems = decorateGroupItems(groupConfigItems, configPhase, topLevelRootName, parentName, additionalNames,
withinAMap, generateSeparateConfigGroupDocs);

// make sure that the config section is added if it is to be shown or when scanning parent configuration group
// priory to scanning configuration roots. This is useful as we get indication of whether the config items are part
Expand All @@ -561,8 +583,15 @@ private List<ConfigDocItem> readConfigGroupItems(ConfigPhase configPhase, String
* The missing information come from configuration roots and these are config phase, top level root name and parent name (as
* we are traversing down the tree)
*/
private List<ConfigDocItem> decorateGroupItems(List<ConfigDocItem> groupConfigItems, ConfigPhase configPhase,
String topLevelRootName, String parentName, boolean withinAMap, boolean generateSeparateConfigGroupDocs) {
private List<ConfigDocItem> decorateGroupItems(
List<ConfigDocItem> groupConfigItems,
ConfigPhase configPhase,
String topLevelRootName,
String parentName,
List<String> additionalNames,
boolean withinAMap,
boolean generateSeparateConfigGroupDocs) {

List<ConfigDocItem> decoratedItems = new ArrayList<>();
for (ConfigDocItem configDocItem : groupConfigItems) {
if (configDocItem.isConfigKey()) {
Expand All @@ -571,6 +600,15 @@ private List<ConfigDocItem> decorateGroupItems(List<ConfigDocItem> groupConfigIt
configDocKey.setWithinAMap(configDocKey.isWithinAMap() || withinAMap);
configDocKey.setWithinAConfigGroup(true);
configDocKey.setTopLevelGrouping(topLevelRootName);
List<String> additionalKeys = new ArrayList<>();
for (String key : configDocKey.getAdditionalKeys()) {
additionalKeys.add(parentName + key);
for (String name : additionalNames) {
additionalKeys.add(name + key);
}
}
additionalKeys.addAll(additionalNames.stream().map(k -> k + configDocKey.getKey()).collect(toList()));
configDocKey.setAdditionalKeys(additionalKeys);
configDocKey.setKey(parentName + configDocKey.getKey());
decoratedItems.add(configDocItem);
} else {
Expand All @@ -584,6 +622,7 @@ private List<ConfigDocItem> decorateGroupItems(List<ConfigDocItem> groupConfigIt
configPhase,
topLevelRootName,
parentName,
additionalNames,
section.isWithinAMap(),
generateSeparateConfigGroupDocs);
String configGroupType = section.getConfigGroupType();
Expand Down
10 changes: 10 additions & 0 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 @@ -2,6 +2,7 @@

import java.io.IOException;
import java.io.Writer;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
import java.util.regex.Matcher;
Expand All @@ -11,6 +12,7 @@
final public class ConfigDocKey implements ConfigDocElement, Comparable<ConfigDocElement> {
private String type;
private String key;
private List<String> additionalKeys = new ArrayList<>();
private String configDoc;
private boolean withinAMap;
private String defaultValue;
Expand Down Expand Up @@ -61,6 +63,14 @@ public void setKey(String key) {
this.key = key;
}

public List<String> getAdditionalKeys() {
return additionalKeys;
}

public void setAdditionalKeys(final List<String> additionalKeys) {
this.additionalKeys = additionalKeys;
}

public void setTopLevelGrouping(String topLevelGrouping) {
this.topLevelGrouping = topLevelGrouping;
}
Expand Down
1 change: 1 addition & 0 deletions ...sor/src/main/java/io/quarkus/annotation/processor/generate_doc/MavenConfigDocBuilder.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ public void addParam(String type, String name, String defaultValue, boolean requ
final ConfigDocKey configDocKey = new ConfigDocKey();
configDocKey.setType(type);
configDocKey.setKey(name);
configDocKey.setAdditionalKeys(List.of(name));
configDocKey.setConfigPhase(ConfigPhase.RUN_TIME);
configDocKey.setDefaultValue(defaultValue == null ? Constants.EMPTY : defaultValue);
if (description != null && !description.isBlank()) {
Expand Down
18 changes: 13 additions & 5 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 @@ -114,11 +114,19 @@ public void format(Writer writer, ConfigDocKey configDocKey) throws IOException
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,
key,

StringBuilder keys = new StringBuilder();
keys.append(
String.format("%s [[%s]]`link:#%s[%s]`\n\n", configDocKey.getConfigPhase().getIllustration(), anchor, anchor,
key));
for (String additionalKey : configDocKey.getAdditionalKeys()) {
if (!additionalKey.equals(key)) {
keys.append(String.format("`link:#%s[%s]`\n\n", anchor, additionalKey));
}
}

writer.append(String.format("\n\na|%s\n[.description]\n--\n%s\n--%s|%s %s\n|%s\n",
keys,
// make sure nobody inserts a table cell separator here
doc.replace("|", "\\|"),
// if ConfigDocKey is enum, cell style operator must support block elements
Expand Down

0 comments on commit ac5b8d0

Please sign in to comment.