Skip to content

Commit

Permalink
Properly generate documents from config groups in ConfigMapping
Browse files Browse the repository at this point in the history
  • Loading branch information
@radcortez
radcortez authored and Alasdair Preston committed Sep 14, 2022
1 parent 36f1509 commit 11e984f
Show file tree
Hide file tree
Showing 6 changed files with 112 additions and 300 deletions.
2 changes: 1 addition & 1 deletion ...processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -460,7 +460,7 @@ private void recordMappingJavadoc(final TypeElement clazz, final Properties java
for (Element e : clazz.getEnclosedElements()) {
switch (e.getKind()) {
case INTERFACE: {
recordMappingJavadoc(((TypeElement) e), javadocProps);
recordMappingJavadoc(((TypeElement) e));
break;
}

Expand Down
62 changes: 37 additions & 25 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 @@ -19,6 +19,7 @@
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 javax.lang.model.element.Modifier.ABSTRACT;

import java.io.IOException;
import java.time.Duration;
Expand Down Expand Up @@ -86,11 +87,11 @@ public ConfigDoItemFinder(Set<ConfigRootInfo> configRoots,
*
*/
ScannedConfigDocsItemHolder findInMemoryConfigurationItems() throws IOException {

for (Map.Entry<String, TypeElement> entry : configGroupQualifiedNameToTypeElementMap.entrySet()) {
ConfigPhase buildTime = ConfigPhase.BUILD_TIME;
final List<ConfigDocItem> configDocItems = recursivelyFindConfigItems(
entry.getValue(), EMPTY, EMPTY, buildTime, false, false, 1, false);
final List<ConfigDocItem> configDocItems = recursivelyFindConfigItems(entry.getValue(), EMPTY, EMPTY, buildTime,
false, 1,
false);
allConfigurationGroups.put(entry.getKey(), OBJECT_MAPPER.writeValueAsString(configDocItems));
}

Expand All @@ -99,9 +100,8 @@ ScannedConfigDocsItemHolder findInMemoryConfigurationItems() throws IOException
final TypeElement element = configRootInfo.getClazz();
String rootName = configRootInfo.getName();
ConfigPhase configPhase = configRootInfo.getConfigPhase();
boolean isMapping = configRootInfo.isMapping();
final List<ConfigDocItem> configDocItems = recursivelyFindConfigItems(element, rootName, rootName, configPhase,
isMapping, false, sectionLevel, true);
false, sectionLevel, true);
holder.addConfigRootItems(configRootInfo, configDocItems);
allConfigurationRoots.put(configRootInfo.getClazz().toString(), OBJECT_MAPPER.writeValueAsString(configDocItems));
}
Expand All @@ -113,8 +113,7 @@ ScannedConfigDocsItemHolder findInMemoryConfigurationItems() throws IOException
* Recursively find config item found in a config root or config group given as {@link Element}
*/
private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String rootName, String parentName,
ConfigPhase configPhase, boolean isMapping, boolean withinAMap, int sectionLevel,
boolean generateSeparateConfigGroupDocsFiles)
ConfigPhase configPhase, boolean withinAMap, int sectionLevel, boolean generateSeparateConfigGroupDocsFiles)
throws JsonProcessingException {
List<ConfigDocItem> configDocItems = new ArrayList<>();
TypeElement asTypeElement = (TypeElement) element;
Expand All @@ -130,7 +129,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
if (rawConfigItems == null) { // element not yet scanned
Element superElement = ((DeclaredType) superType).asElement();
superTypeConfigItems = recursivelyFindConfigItems(superElement, rootName, parentName,
configPhase, isMapping, withinAMap, sectionLevel, generateSeparateConfigGroupDocsFiles);
configPhase, withinAMap, sectionLevel, generateSeparateConfigGroupDocsFiles);
} else {
superTypeConfigItems = OBJECT_MAPPER.readValue(rawConfigItems, LIST_OF_CONFIG_ITEMS_TYPE_REF);
}
Expand All @@ -139,7 +138,9 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
}

for (Element enclosedElement : element.getEnclosedElements()) {
if (!enclosedElement.getKind().isField() && (!isMapping || !enclosedElement.getKind().equals(ElementKind.METHOD))) {
shouldProcessElement(enclosedElement);

if (!shouldProcessElement(enclosedElement)) {
continue;
}

Expand Down Expand Up @@ -221,15 +222,13 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
}

// Mappings
if (isMapping) {
for (Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry : annotationMirror
.getElementValues().entrySet()) {
Object value = entry.getValue().getValue();
if (annotationName.equals(ANNOTATION_CONFIG_WITH_NAME)) {
name = parentName + DOT + value;
} else if (annotationName.equals(ANNOTATION_CONFIG_WITH_DEFAULT)) {
defaultValue = value.toString();
}
for (Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry : annotationMirror
.getElementValues().entrySet()) {
Object value = entry.getValue().getValue();
if (annotationName.equals(ANNOTATION_CONFIG_WITH_NAME)) {
name = parentName + DOT + value;
} else if (annotationName.equals(ANNOTATION_CONFIG_WITH_DEFAULT)) {
defaultValue = value.toString();
}
}
}
Expand All @@ -254,7 +253,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r

if (isConfigGroup(type)) {
List<ConfigDocItem> groupConfigItems = readConfigGroupItems(configPhase, rootName, name, type,
configSection, isMapping, withinAMap, generateSeparateConfigGroupDocsFiles);
configSection, withinAMap, generateSeparateConfigGroupDocsFiles);
DocGeneratorUtil.appendConfigItemsIntoExistingOnes(configDocItems, groupConfigItems);
} else {
final ConfigDocKey configDocKey = new ConfigDocKey();
Expand All @@ -278,7 +277,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
if (isConfigGroup(type)) {
name += String.format(NAMED_MAP_CONFIG_ITEM_FORMAT, configDocMapKey);
List<ConfigDocItem> groupConfigItems = readConfigGroupItems(configPhase, rootName, name, type,
configSection, isMapping, true, generateSeparateConfigGroupDocsFiles);
configSection, true, generateSeparateConfigGroupDocsFiles);
DocGeneratorUtil.appendConfigItemsIntoExistingOnes(configDocItems, groupConfigItems);
continue;
} else {
Expand All @@ -304,8 +303,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
}
configSection.setOptional(true);
List<ConfigDocItem> groupConfigItems = readConfigGroupItems(configPhase, rootName, name,
typeInString, configSection, isMapping, withinAMap,
generateSeparateConfigGroupDocsFiles);
typeInString, configSection, withinAMap, generateSeparateConfigGroupDocsFiles);
DocGeneratorUtil.appendConfigItemsIntoExistingOnes(configDocItems, groupConfigItems);
continue;
} else if ((typeInString.startsWith(List.class.getName())
Expand Down Expand Up @@ -390,6 +388,20 @@ private boolean isConfigGroup(String type) {
return configGroupQualifiedNameToTypeElementMap.containsKey(type) || allConfigurationGroups.hasKey(type);
}

private boolean shouldProcessElement(final Element enclosedElement) {
if (enclosedElement.getKind().isField()) {
return true;
}

// A ConfigMapping method
if (enclosedElement.getKind().equals(ElementKind.METHOD)) {
Element enclosingElement = enclosedElement.getEnclosingElement();
return enclosingElement.getModifiers().contains(ABSTRACT) && enclosedElement.getModifiers().contains(ABSTRACT);
}

return false;
}

private String simpleTypeToString(TypeMirror typeMirror) {
if (typeMirror.getKind().isPrimitive()) {
return typeMirror.toString();
Expand Down Expand Up @@ -456,8 +468,8 @@ private boolean isDurationType(TypeMirror realTypeMirror) {
*
*/
private List<ConfigDocItem> readConfigGroupItems(ConfigPhase configPhase, String topLevelRootName, String parentName,
String configGroup, ConfigDocSection configSection, boolean isMapping, boolean withinAMap,
boolean generateSeparateConfigGroupDocs) throws JsonProcessingException {
String configGroup, ConfigDocSection configSection, boolean withinAMap, boolean generateSeparateConfigGroupDocs)
throws JsonProcessingException {

configSection.setConfigGroupType(configGroup);
if (configSection.getSectionDetailsTitle() == null) {
Expand All @@ -475,7 +487,7 @@ private List<ConfigDocItem> readConfigGroupItems(ConfigPhase configPhase, String
groupConfigItems = OBJECT_MAPPER.readValue(property, LIST_OF_CONFIG_ITEMS_TYPE_REF);
} else {
TypeElement configGroupTypeElement = configGroupQualifiedNameToTypeElementMap.get(configGroup);
groupConfigItems = recursivelyFindConfigItems(configGroupTypeElement, EMPTY, EMPTY, configPhase, isMapping,
groupConfigItems = recursivelyFindConfigItems(configGroupTypeElement, EMPTY, EMPTY, configPhase,
false, 1, generateSeparateConfigGroupDocs);
allConfigurationGroups.put(configGroup, OBJECT_MAPPER.writeValueAsString(groupConfigItems));
}
Expand Down
4 changes: 1 addition & 3 deletions ...ssor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemScanner.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,6 @@ public void addConfigRoot(final PackageElement pkg, TypeElement clazz) {

String prefix = Constants.QUARKUS;
ConfigPhase configPhase = ConfigPhase.BUILD_TIME;
boolean isMapping = false;

for (AnnotationMirror annotationMirror : clazz.getAnnotationMirrors()) {
String annotationName = annotationMirror.getAnnotationType().toString();
Expand All @@ -88,7 +87,6 @@ public void addConfigRoot(final PackageElement pkg, TypeElement clazz) {

for (AnnotationMirror mirror : clazz.getAnnotationMirrors()) {
if (mirror.getAnnotationType().toString().equals(Constants.ANNOTATION_CONFIG_MAPPING)) {
isMapping = true;
name = Constants.EMPTY;
for (Entry<? extends ExecutableElement, ? extends AnnotationValue> entry : mirror.getElementValues()
.entrySet()) {
Expand All @@ -113,7 +111,7 @@ public void addConfigRoot(final PackageElement pkg, TypeElement clazz) {
fileName = name.replace(Constants.DOT, Constants.DASH.charAt(0)) + Constants.ADOC_EXTENSION;
}

ConfigRootInfo configRootInfo = new ConfigRootInfo(name, clazz, configPhase, isMapping, fileName);
ConfigRootInfo configRootInfo = new ConfigRootInfo(name, clazz, configPhase, fileName);
configRoots.add(configRootInfo);
break;
}
Expand Down
15 changes: 4 additions & 11 deletions .../processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigRootInfo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,16 @@ final public class ConfigRootInfo {
private final String name;
private final TypeElement clazz;
private final ConfigPhase configPhase;
private final boolean mapping;
private final String fileName;

public ConfigRootInfo(
final String name,
final TypeElement clazz,
final ConfigPhase configPhase, final boolean mapping, final String fileName) {
final ConfigPhase configPhase,
final String fileName) {
this.name = name;
this.clazz = clazz;
this.configPhase = configPhase;
this.mapping = mapping;
this.fileName = fileName;
}

Expand All @@ -35,16 +34,15 @@ public boolean equals(final Object o) {
return false;
}
final ConfigRootInfo that = (ConfigRootInfo) o;
return mapping == that.mapping &&
name.equals(that.name) &&
return name.equals(that.name) &&
clazz.equals(that.clazz) &&
configPhase == that.configPhase &&
fileName.equals(that.fileName);
}

@Override
public int hashCode() {
return Objects.hash(name, clazz, configPhase, mapping, fileName);
return Objects.hash(name, clazz, configPhase, fileName);
}

@Override
Expand All @@ -53,7 +51,6 @@ public String toString() {
"name='" + name + '\'' +
", clazz=" + clazz +
", configPhase=" + configPhase +
", mapping=" + mapping +
", fileName='" + fileName + '\'' +
'}';
}
Expand All @@ -69,8 +66,4 @@ public TypeElement getClazz() {
public ConfigPhase getConfigPhase() {
return configPhase;
}

public boolean isMapping() {
return mapping;
}
}
7 changes: 4 additions & 3 deletions docs/src/main/asciidoc/platform.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,13 +111,14 @@ Extension developers that want to make their configuration options platform-spec
package io.quarkus.deployment.pkg;
@ConfigRoot(phase = ConfigPhase.BUILD_TIME)
public class NativeConfig {
@ConfigMapping(prefix = "quarkus")
public interface NativeConfig {
/**
* The docker image to use to do the image build
*/
@ConfigItem(defaultValue = "${platform.quarkus.native.builder-image}")
public String builderImage;
@WithDefault("${platform.quarkus.native.builder-image}")
String builderImage();
}
----

Expand Down
Loading

0 comments on commit 11e984f

Please sign in to comment.