From 7773394e93139b5c11e59a70f3977c0281277d3a Mon Sep 17 00:00:00 2001 From: Guillaume Smet Date: Sat, 24 Aug 2024 14:50:43 +0200 Subject: [PATCH] Config Doc - Clarify how paths are handled Group the property and the environment variable in the path so that we can also collect environment variables for additional paths. --- build-parent/pom.xml | 16 +++++++++- core/processor/pom.xml | 4 +++ .../config/model/AbstractConfigItem.java | 17 ++++++++-- .../config/model/ConfigProperty.java | 31 ++++++++++++++----- .../config/model/ConfigRoot.java | 4 +-- .../config/model/ConfigSection.java | 16 ++++++++-- .../config/resolver/ConfigResolver.java | 26 ++++++++++------ .../config/doc/GenerateAsciidocMojo.java | 12 +++---- .../templates/tags/configProperty.qute.adoc | 4 +-- .../resources/templates/tags/envVar.qute.adoc | 4 +-- 10 files changed, 99 insertions(+), 35 deletions(-) diff --git a/build-parent/pom.xml b/build-parent/pom.xml index e88fabf397a3b..7e60735361603 100644 --- a/build-parent/pom.xml +++ b/build-parent/pom.xml @@ -26,6 +26,7 @@ 4.9.2 ${scala-maven-plugin.version} + 1.6.Final 3.2.2 @@ -645,7 +646,20 @@ - + + org.jboss.bridger + bridger + ${jboss-bridger-plugin.version} + + + weave + process-classes + + transform + + + + diff --git a/core/processor/pom.xml b/core/processor/pom.xml index 20ef6ea3d0185..44d6366b1499b 100644 --- a/core/processor/pom.xml +++ b/core/processor/pom.xml @@ -88,6 +88,10 @@ -proc:none + + org.jboss.bridger + bridger + diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/AbstractConfigItem.java b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/AbstractConfigItem.java index 0ebc6db6a794a..b6095aa69c73c 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/AbstractConfigItem.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/AbstractConfigItem.java @@ -9,13 +9,13 @@ public sealed abstract class AbstractConfigItem implements Comparable additionalPaths; - private final String environmentVariable; + private final List additionalPaths; private final String typeDescription; private final boolean map; @@ -28,16 +29,16 @@ public final class ConfigProperty extends AbstractConfigItem { private final String javadocSiteLink; - public ConfigProperty(ConfigPhase phase, String sourceClass, String sourceName, String path, List additionalPaths, - String environmentVariable, String type, String typeDescription, boolean map, boolean list, boolean optional, + public ConfigProperty(ConfigPhase phase, String sourceClass, String sourceName, PropertyPath path, + List additionalPaths, String type, String typeDescription, boolean map, boolean list, + boolean optional, String mapKey, boolean unnamedMapKey, boolean withinMap, boolean converted, @JsonProperty("enum") boolean isEnum, EnumAcceptedValues enumAcceptedValues, String defaultValue, String javadocSiteLink, boolean deprecated) { super(sourceClass, sourceName, path, type, deprecated); this.phase = phase; - this.additionalPaths = additionalPaths != null ? additionalPaths : List.of(); - this.environmentVariable = environmentVariable; + this.additionalPaths = additionalPaths != null ? Collections.unmodifiableList(additionalPaths) : List.of(); this.typeDescription = typeDescription; this.map = map; this.list = list; @@ -56,12 +57,18 @@ public ConfigPhase getPhase() { return phase; } - public List getAdditionalPaths() { + public PropertyPath getPath() { + return (PropertyPath) super.getPath(); + } + + public List getAdditionalPaths() { return additionalPaths; } + @Deprecated + @JsonIgnore public String getEnvironmentVariable() { - return environmentVariable; + return getPath().environmentVariable(); } public String getTypeDescription() { @@ -150,4 +157,12 @@ public boolean hasMemorySizeType() { protected void walk(ConfigItemVisitor visitor) { visitor.visit(this); } + + public record PropertyPath(String property, String environmentVariable) implements Path { + + @Override + public String toString() { + return property(); + } + } } diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigRoot.java b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigRoot.java index e6915e718348e..886f387ca4b20 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigRoot.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigRoot.java @@ -77,7 +77,7 @@ public void merge(ConfigRoot other) { for (AbstractConfigItem otherItem : other.getItems()) { if (otherItem instanceof ConfigSection otherConfigSection) { - ConfigSection similarConfigSection = existingConfigSections.get(otherConfigSection.getPath()); + ConfigSection similarConfigSection = existingConfigSections.get(otherConfigSection.getPath().property()); if (similarConfigSection == null) { this.items.add(otherConfigSection); @@ -97,7 +97,7 @@ public void merge(ConfigRoot other) { private void collectConfigSections(Map configSections, ConfigItemCollection configItemCollection) { for (AbstractConfigItem item : configItemCollection.getItems()) { if (item instanceof ConfigSection configSection) { - configSections.put(item.getPath(), configSection); + configSections.put(item.getPath().property(), configSection); collectConfigSections(configSections, configSection); } diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigSection.java b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigSection.java index 0bce14a1c8e2b..1cbacbae64998 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigSection.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigSection.java @@ -11,7 +11,7 @@ public final class ConfigSection extends AbstractConfigItem implements ConfigIte private final List items = new ArrayList<>(); private final int level; - public ConfigSection(String sourceClass, String sourceName, String path, String type, int level, + public ConfigSection(String sourceClass, String sourceName, SectionPath path, String type, int level, boolean generated, boolean deprecated) { super(sourceClass, sourceName, path, type, deprecated); this.generated = generated; @@ -37,6 +37,10 @@ public int compareTo(AbstractConfigItem o) { return 0; } + public SectionPath getPath() { + return (SectionPath) super.getPath(); + } + public boolean isSection() { return true; } @@ -71,7 +75,7 @@ public void merge(ConfigSection other, Map existingConfig for (AbstractConfigItem otherItem : other.getItems()) { if (otherItem instanceof ConfigSection otherConfigSection) { - ConfigSection similarConfigSection = existingConfigSections.get(otherConfigSection.getPath()); + ConfigSection similarConfigSection = existingConfigSections.get(otherConfigSection.getPath().property()); if (similarConfigSection == null) { this.items.add(otherConfigSection); } else { @@ -114,4 +118,12 @@ protected void walk(ConfigItemVisitor visitor) { item.walk(visitor); } } + + public record SectionPath(String property) implements Path { + + @Override + public String toString() { + return property(); + } + } } diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/resolver/ConfigResolver.java b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/resolver/ConfigResolver.java index 07f3f6cf98a9f..9e79083966110 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/resolver/ConfigResolver.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/resolver/ConfigResolver.java @@ -22,8 +22,10 @@ import io.quarkus.annotation.processor.documentation.config.model.ConfigItemCollection; import io.quarkus.annotation.processor.documentation.config.model.ConfigPhase; import io.quarkus.annotation.processor.documentation.config.model.ConfigProperty; +import io.quarkus.annotation.processor.documentation.config.model.ConfigProperty.PropertyPath; import io.quarkus.annotation.processor.documentation.config.model.ConfigRoot; import io.quarkus.annotation.processor.documentation.config.model.ConfigSection; +import io.quarkus.annotation.processor.documentation.config.model.ConfigSection.SectionPath; import io.quarkus.annotation.processor.documentation.config.model.EnumAcceptedValues; import io.quarkus.annotation.processor.documentation.config.model.EnumAcceptedValues.EnumAcceptedValue; import io.quarkus.annotation.processor.documentation.config.model.JavadocElements; @@ -88,7 +90,7 @@ public ResolvedModel resolveModel() { private void resolveProperty(ConfigRoot configRoot, Map existingRootConfigSections, ConfigPhase phase, ResolutionContext context, DiscoveryConfigProperty discoveryConfigProperty) { - String propertyPath = appendPath(context.getPath(), discoveryConfigProperty.getPath()); + String path = appendPath(context.getPath(), discoveryConfigProperty.getPath()); List additionalPaths = context.getAdditionalPaths().stream() .map(p -> appendPath(p, discoveryConfigProperty.getPath())) @@ -100,13 +102,13 @@ private void resolveProperty(ConfigRoot configRoot, Map e if (configCollector.isResolvedConfigGroup(typeQualifiedName)) { DiscoveryConfigGroup discoveryConfigGroup = configCollector.getResolvedConfigGroup(typeQualifiedName); - String potentiallyMappedPath = propertyPath; + String potentiallyMappedPath = path; if (discoveryConfigProperty.getType().isMap()) { if (discoveryConfigProperty.isUnnamedMapKey()) { ListIterator additionalPathsIterator = additionalPaths.listIterator(); additionalPathsIterator - .add(propertyPath + ConfigNamingUtil.getMapKey(discoveryConfigProperty.getMapKey())); + .add(path + ConfigNamingUtil.getMapKey(discoveryConfigProperty.getMapKey())); while (additionalPathsIterator.hasNext()) { additionalPathsIterator.add(additionalPathsIterator.next() + ConfigNamingUtil.getMapKey(discoveryConfigProperty.getMapKey())); @@ -125,16 +127,16 @@ private void resolveProperty(ConfigRoot configRoot, Map e boolean isWithMapWithUnnamedKey = context.isWithinMapWithUnnamedKey() || discoveryConfigProperty.isUnnamedMapKey(); if (discoveryConfigProperty.isSection()) { - ConfigSection configSection = existingRootConfigSections.get(propertyPath); + ConfigSection configSection = existingRootConfigSections.get(path); if (configSection != null) { configSection.appendState(discoveryConfigProperty.isSectionGenerated(), deprecated); } else { configSection = new ConfigSection(discoveryConfigProperty.getSourceClass(), - discoveryConfigProperty.getSourceName(), propertyPath, typeQualifiedName, + discoveryConfigProperty.getSourceName(), new SectionPath(path), typeQualifiedName, context.getSectionLevel(), discoveryConfigProperty.isSectionGenerated(), deprecated); context.getItemCollection().addItem(configSection); - existingRootConfigSections.put(propertyPath, configSection); + existingRootConfigSections.put(path, configSection); } configGroupContext = new ResolutionContext(potentiallyMappedPath, additionalPaths, discoveryConfigGroup, @@ -172,7 +174,7 @@ private void resolveProperty(ConfigRoot configRoot, Map e enumAcceptedValues = new EnumAcceptedValues(enumDefinition.qualifiedName(), localAcceptedValues); } - String potentiallyMappedPath = propertyPath; + String potentiallyMappedPath = path; boolean optional = discoveryConfigProperty.getType().isOptional(); if (discoveryConfigProperty.getType().isMap()) { @@ -189,11 +191,17 @@ private void resolveProperty(ConfigRoot configRoot, Map e typeQualifiedName = discoveryConfigProperty.getType().wrapperType().toString(); } + PropertyPath propertyPath = new PropertyPath(potentiallyMappedPath, + ConfigNamingUtil.toEnvVarName(potentiallyMappedPath)); + List additionalPropertyPaths = additionalPaths.stream() + .map(ap -> new PropertyPath(ap, ConfigNamingUtil.toEnvVarName(ap))) + .toList(); + // this is a standard property ConfigProperty configProperty = new ConfigProperty(phase, discoveryConfigProperty.getSourceClass(), - discoveryConfigProperty.getSourceName(), potentiallyMappedPath, additionalPaths, - ConfigNamingUtil.toEnvVarName(potentiallyMappedPath), typeQualifiedName, typeSimplifiedName, + discoveryConfigProperty.getSourceName(), propertyPath, additionalPropertyPaths, + typeQualifiedName, typeSimplifiedName, discoveryConfigProperty.getType().isMap(), discoveryConfigProperty.getType().isList(), optional, discoveryConfigProperty.getMapKey(), discoveryConfigProperty.isUnnamedMapKey(), context.isWithinMap(), diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateAsciidocMojo.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateAsciidocMojo.java index bd9c3c74aadba..37d64e21faa92 100644 --- a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateAsciidocMojo.java +++ b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateAsciidocMojo.java @@ -154,17 +154,17 @@ public void execute() throws MojoExecutionException, MojoFailureException { for (ConfigSection generatedConfigSection : extensionConfigSectionsEntry.getValue()) { Path configSectionAdocPath = resolvedTargetDirectory.resolve(String.format(CONFIG_ROOT_FILE_FORMAT, - extension.artifactId(), cleanSectionPath(generatedConfigSection.getPath()))); + extension.artifactId(), cleanSectionPath(generatedConfigSection.getPath().property()))); String summaryTableId = asciidocFormatter - .toAnchor(extension.artifactId() + "_" + generatedConfigSection.getPath()); + .toAnchor(extension.artifactId() + "_" + generatedConfigSection.getPath().property()); try { Files.writeString(configSectionAdocPath, generateConfigReference(quteEngine, summaryTableId, extension, generatedConfigSection, - "_" + generatedConfigSection.getPath(), false)); + "_" + generatedConfigSection.getPath().property(), false)); } catch (Exception e) { throw new MojoExecutionException( - "Unable to render config section for section: " + generatedConfigSection.getPath() + "Unable to render config section for section: " + generatedConfigSection.getPath().property() + " in extension: " + extension, e); } @@ -275,7 +275,7 @@ private static Engine initializeQuteEngine(AsciidocFormatter asciidocFormatter) .artifactId() + // the additional suffix ctx.evaluate(ctx.getParams().get(1)).toCompletableFuture().join() + - "_" + ((ConfigProperty) ctx.getBase()).getPath())) + "_" + ((ConfigProperty) ctx.getBase()).getPath().property())) .build()) // we need a different anchor for sections as otherwise we can have a conflict // (typically when you have an `enabled` property with parent name just under the section level) @@ -288,7 +288,7 @@ private static Engine initializeQuteEngine(AsciidocFormatter asciidocFormatter) .artifactId() + // the additional suffix ctx.evaluate(ctx.getParams().get(1)).toCompletableFuture().join() + - "_section_" + ((ConfigSection) ctx.getBase()).getPath())) + "_section_" + ((ConfigSection) ctx.getBase()).getPath().property())) .build()) .addValueResolver(ValueResolver.builder() .applyToBaseClass(ConfigProperty.class) diff --git a/devtools/config-doc-maven-plugin/src/main/resources/templates/tags/configProperty.qute.adoc b/devtools/config-doc-maven-plugin/src/main/resources/templates/tags/configProperty.qute.adoc index dd3a23f0d0abc..709f74721a6d1 100644 --- a/devtools/config-doc-maven-plugin/src/main/resources/templates/tags/configProperty.qute.adoc +++ b/devtools/config-doc-maven-plugin/src/main/resources/templates/tags/configProperty.qute.adoc @@ -1,7 +1,7 @@ -a|{#if configProperty.phase.fixedAtBuildTime}icon:lock[title=Fixed at build time]{/if} [[{configProperty.toAnchor(extension, additionalAnchorPrefix)}]] [.property-path]##`{configProperty.path}`## +a|{#if configProperty.phase.fixedAtBuildTime}icon:lock[title=Fixed at build time]{/if} [[{configProperty.toAnchor(extension, additionalAnchorPrefix)}]] [.property-path]##`{configProperty.path.property}`## {#for additionalPath in configProperty.additionalPaths} -`{additionalPath}` +`{additionalPath.property}` {/for} [.description] diff --git a/devtools/config-doc-maven-plugin/src/main/resources/templates/tags/envVar.qute.adoc b/devtools/config-doc-maven-plugin/src/main/resources/templates/tags/envVar.qute.adoc index d595945bcdc94..75383e8c814e9 100644 --- a/devtools/config-doc-maven-plugin/src/main/resources/templates/tags/envVar.qute.adoc +++ b/devtools/config-doc-maven-plugin/src/main/resources/templates/tags/envVar.qute.adoc @@ -1,6 +1,6 @@ ifdef::add-copy-button-to-env-var[] -Environment variable: env_var_with_copy_button:+++{configProperty.environmentVariable}+++[] +Environment variable: env_var_with_copy_button:+++{configProperty.path.environmentVariable}+++[] endif::add-copy-button-to-env-var[] ifndef::add-copy-button-to-env-var[] -Environment variable: `+++{configProperty.environmentVariable}+++` +Environment variable: `+++{configProperty.path.environmentVariable}+++` endif::add-copy-button-to-env-var[]