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

Improve config documentation generation for mappings #34069

Merged
merged 1 commit into from
Jun 28, 2023
Merged

Improve config documentation generation for mappings #34069

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
48 changes: 47 additions & 1 deletion ...processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package io.quarkus.annotation.processor;

import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_GROUP;
import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_MAPPING;
import static javax.lang.model.util.ElementFilter.constructorsIn;
import static javax.lang.model.util.ElementFilter.fieldsIn;
Expand Down Expand Up @@ -27,6 +28,7 @@
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Properties;
import java.util.Set;
import java.util.TreeSet;
Expand Down Expand Up @@ -545,11 +547,55 @@ private void processMethodConfigItem(ExecutableElement method, Properties javado

private void processMethodConfigMapping(ExecutableElement method, Properties javadocProps, String className) {
if (method.getModifiers().contains(Modifier.ABSTRACT)) {
final String docComment = getRequiredJavadoc(method);
// Skip toString method, because mappings can include it and generate it
if (method.getSimpleName().contentEquals("toString") && method.getParameters().size() == 0) {
return;
}

String docComment = getRequiredJavadoc(method);
javadocProps.put(className + Constants.DOT + method.getSimpleName().toString(), docComment);

// Find groups without annotation
TypeMirror returnType = method.getReturnType();
if (TypeKind.DECLARED.equals(returnType.getKind())) {
DeclaredType declaredType = (DeclaredType) returnType;
if (!isAnnotationPresent(declaredType.asElement(), ANNOTATION_CONFIG_GROUP)) {
TypeElement type = unwrapConfigGroup(returnType);
if (type != null && ElementKind.INTERFACE.equals(type.getKind())) {
recordMappingJavadoc(type);
configDocItemScanner.addConfigGroups(type);
}
}
}
}
}

private TypeElement unwrapConfigGroup(TypeMirror typeMirror) {
if (typeMirror == null) {
return null;
}

DeclaredType declaredType = (DeclaredType) typeMirror;
String name = declaredType.asElement().toString();
List<? extends TypeMirror> typeArguments = declaredType.getTypeArguments();
if (typeArguments.size() == 0) {
if (!name.startsWith("java.")) {
return (TypeElement) declaredType.asElement();
}
} else if (typeArguments.size() == 1) {
if (name.equals(Optional.class.getName()) ||
name.equals(List.class.getName()) ||
name.equals(Set.class.getName())) {
return unwrapConfigGroup(typeArguments.get(0));
}
} else if (typeArguments.size() == 2) {
if (name.equals(Map.class.getName())) {
return unwrapConfigGroup(typeArguments.get(1));
}
}
return null;
}

private void processConfigGroup(RoundEnvironment roundEnv, TypeElement annotation) {
final Set<String> groupClassNames = new HashSet<>();
for (TypeElement i : typesIn(roundEnv.getElementsAnnotatedWith(annotation))) {
Expand Down
13 changes: 8 additions & 5 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 @@ -271,7 +271,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
if (!typeArguments.isEmpty()) {
// FIXME: this is super dodgy: we should check the type!!
if (typeArguments.size() == 2) {
type = typeArguments.get(1).toString();
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,
Expand Down Expand Up @@ -354,8 +354,6 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
}
}

final String configDescription = javaDocParser.parseConfigDescription(rawJavaDoc);

configDocKey.setKey(name);
configDocKey.setType(type);
configDocKey.setList(list);
Expand All @@ -365,7 +363,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String r
configDocKey.setConfigPhase(configPhase);
configDocKey.setDefaultValue(defaultValue);
configDocKey.setDocMapKey(configDocMapKey);
configDocKey.setConfigDoc(configDescription);
configDocKey.setConfigDoc(javaDocParser.parseConfigDescription(rawJavaDoc));
configDocKey.setAcceptedValues(acceptedValues);
configDocKey.setJavaDocSiteLink(getJavaDocSiteLink(type));
ConfigDocItem configDocItem = new ConfigDocItem();
Expand Down Expand Up @@ -413,6 +411,11 @@ private boolean shouldProcessElement(final Element enclosedElement) {

// A ConfigMapping method
if (enclosedElement.getKind().equals(ElementKind.METHOD)) {
ExecutableElement method = (ExecutableElement) enclosedElement;
// Skip toString method, because mappings can include it and generate it
if (method.getSimpleName().contentEquals("toString") && method.getParameters().size() == 0) {
return false;
}
Element enclosingElement = enclosedElement.getEnclosingElement();
return enclosingElement.getModifiers().contains(ABSTRACT) && enclosedElement.getModifiers().contains(ABSTRACT);
}
Expand All @@ -438,7 +441,7 @@ private String simpleTypeToString(TypeMirror typeMirror) {
return simpleTypeToString(typeArguments.get(0));
}

return typeMirror.toString();
return getType(typeMirror);
}

private List<String> extractEnumValues(TypeMirror realTypeMirror, boolean useHyphenatedEnumValue, String javaDocKey) {
Expand Down