Merge pull request #42744 from gsmet/clarify-paths

Config Doc - Clarify how paths are handled

build-parent/pom.xml

@@ -26,6 +26,7 @@
         <scala-maven-plugin.version>4.9.2</scala-maven-plugin.version>
         <!-- not pretty but this is used in the codestarts and we don't want to break compatibility -->
         <scala-plugin.version>${scala-maven-plugin.version}</scala-plugin.version>
+        <jboss-bridger-plugin.version>1.6.Final</jboss-bridger-plugin.version>
 
         <!-- Jandex versions -->
         <jandex.version>3.2.2</jandex.version>
@@ -645,7 +646,20 @@
                         </execution>
                     </executions>
                 </plugin>
-
+                <plugin>
+                    <groupId>org.jboss.bridger</groupId>
+                    <artifactId>bridger</artifactId>
+                    <version>${jboss-bridger-plugin.version}</version>
+                    <executions>
+                        <execution>
+                            <id>weave</id>
+                            <phase>process-classes</phase>
+                            <goals>
+                                <goal>transform</goal>
+                            </goals>
+                        </execution>
+                    </executions>
+                </plugin>
             </plugins>
         </pluginManagement>
     </build>

core/processor/pom.xml

@@ -88,6 +88,10 @@
                     <compilerArgument>-proc:none</compilerArgument>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.jboss.bridger</groupId>
+                <artifactId>bridger</artifactId>
+            </plugin>
         </plugins>
     </build>
 

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<AbstractCo
 
     protected final String sourceClass;
     protected final String sourceName;
-    protected final String path;
+    protected final Path path;
 
     protected final String type;
 
     protected boolean deprecated;
 
-    public AbstractConfigItem(String sourceClass, String sourceName, String path, String type, boolean deprecated) {
+    public AbstractConfigItem(String sourceClass, String sourceName, Path path, String type, boolean deprecated) {
         this.sourceClass = sourceClass;
         this.sourceName = sourceName;
         this.path = path;
@@ -31,10 +31,16 @@ public String getSourceName() {
         return sourceName;
     }
 
-    public String getPath() {
+    public Path getPath() {
         return path;
     }
 
+    @Deprecated
+    @JsonIgnore
+    public String getPath$$bridge() {
+        return path.property();
+    }
+
     public String getType() {
         return type;
     }
@@ -53,4 +59,9 @@ public boolean isDeprecated() {
     public abstract boolean hasMemorySizeType();
 
     protected abstract void walk(ConfigItemVisitor visitor);
+
+    @JsonTypeInfo(use = JsonTypeInfo.Id.CLASS, include = JsonTypeInfo.As.PROPERTY, property = "@class")
+    public interface Path {
+        String property();
+    }
 }

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigProperty.java

@@ -1,17 +1,18 @@
 package io.quarkus.annotation.processor.documentation.config.model;
 
 import java.time.Duration;
+import java.util.Collections;
 import java.util.List;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import io.quarkus.annotation.processor.documentation.config.util.Types;
 
 public final class ConfigProperty extends AbstractConfigItem {
 
     private final ConfigPhase phase;
-    private final List<String> additionalPaths;
-    private final String environmentVariable;
+    private final List<PropertyPath> 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<String> additionalPaths,
-            String environmentVariable, String type, String typeDescription, boolean map, boolean list, boolean optional,
+    public ConfigProperty(ConfigPhase phase, String sourceClass, String sourceName, PropertyPath path,
+            List<PropertyPath> 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<String> getAdditionalPaths() {
+    public PropertyPath getPath() {
+        return (PropertyPath) super.getPath();
+    }
+
+    public List<PropertyPath> 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();
+        }
+    }
 }

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<String, ConfigSection> 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);
             }

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<AbstractConfigItem> 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<String, ConfigSection> 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();
+        }
+    }
 }

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<String, ConfigSection> existingRootConfigSections,
             ConfigPhase phase, ResolutionContext context, DiscoveryConfigProperty discoveryConfigProperty) {
-        String propertyPath = appendPath(context.getPath(), discoveryConfigProperty.getPath());
+        String path = appendPath(context.getPath(), discoveryConfigProperty.getPath());
 
         List<String> additionalPaths = context.getAdditionalPaths().stream()
                 .map(p -> appendPath(p, discoveryConfigProperty.getPath()))
@@ -100,13 +102,13 @@ private void resolveProperty(ConfigRoot configRoot, Map<String, ConfigSection> e
         if (configCollector.isResolvedConfigGroup(typeQualifiedName)) {
             DiscoveryConfigGroup discoveryConfigGroup = configCollector.getResolvedConfigGroup(typeQualifiedName);
 
-            String potentiallyMappedPath = propertyPath;
+            String potentiallyMappedPath = path;
             if (discoveryConfigProperty.getType().isMap()) {
                 if (discoveryConfigProperty.isUnnamedMapKey()) {
                     ListIterator<String> 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<String, ConfigSection> 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<String, ConfigSection> 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<String, ConfigSection> e
                 typeQualifiedName = discoveryConfigProperty.getType().wrapperType().toString();
             }
 
+            PropertyPath propertyPath = new PropertyPath(potentiallyMappedPath,
+                    ConfigNamingUtil.toEnvVarName(potentiallyMappedPath));
+            List<PropertyPath> 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(),

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)

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]

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[]