Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Support @WithUnnamedKey in documentation #34514

Merged
merged 1 commit into from
Jul 4, 2023
Merged

Support @WithUnnamedKey in documentation #34514

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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