Config Doc - Rewrite xrefs for all config guide

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/discovery/DiscoveryConfigProperty.java

@@ -1,16 +1,16 @@
 package io.quarkus.annotation.processor.documentation.config.discovery;
 
 import io.quarkus.annotation.processor.documentation.config.model.Deprecation;
-import io.quarkus.annotation.processor.documentation.config.model.SourceType;
+import io.quarkus.annotation.processor.documentation.config.model.SourceElementType;
 import io.quarkus.annotation.processor.documentation.config.util.TypeUtil;
 import io.quarkus.annotation.processor.util.Strings;
 
 public class DiscoveryConfigProperty {
 
     private final String path;
-    private final String sourceClass;
-    private final String sourceName;
-    private final SourceType sourceType;
+    private final String sourceType;
+    private final String sourceElementName;
+    private final SourceElementType sourceElementType;
     private final String defaultValue;
     private final String defaultValueForDoc;
     private final Deprecation deprecation;
@@ -22,15 +22,16 @@ public class DiscoveryConfigProperty {
     private final boolean section;
     private final boolean sectionGenerated;
 
-    public DiscoveryConfigProperty(String path, String sourceClass, String sourceName, SourceType sourceType,
+    public DiscoveryConfigProperty(String path, String sourceType, String sourceElementName,
+            SourceElementType sourceElementType,
             String defaultValue,
             String defaultValueForDoc, Deprecation deprecation, String mapKey, boolean unnamedMapKey,
             ResolvedType type, boolean converted, boolean enforceHyphenateEnumValue,
             boolean section, boolean sectionGenerated) {
         this.path = path;
-        this.sourceClass = sourceClass;
-        this.sourceName = sourceName;
         this.sourceType = sourceType;
+        this.sourceElementName = sourceElementName;
+        this.sourceElementType = sourceElementType;
         this.defaultValue = defaultValue;
         this.defaultValueForDoc = defaultValueForDoc;
         this.deprecation = deprecation;
@@ -47,16 +48,16 @@ public String getPath() {
         return path;
     }
 
-    public String getSourceClass() {
-        return sourceClass;
+    public String getSourceType() {
+        return sourceType;
     }
 
-    public String getSourceName() {
-        return sourceName;
+    public String getSourceElementName() {
+        return sourceElementName;
     }
 
-    public SourceType getSourceType() {
-        return sourceType;
+    public SourceElementType getSourceElementType() {
+        return sourceElementType;
     }
 
     public String getDefaultValue() {
@@ -110,8 +111,8 @@ public String toString() {
     public String toString(String prefix) {
         StringBuilder sb = new StringBuilder();
         sb.append(prefix + "name = " + path + "\n");
-        sb.append(prefix + "sourceClass = " + sourceClass + "\n");
-        sb.append(prefix + "sourceName = " + sourceName + "\n");
+        sb.append(prefix + "sourceType = " + sourceType + "\n");
+        sb.append(prefix + "sourceElementName = " + sourceElementName + "\n");
         sb.append(prefix + "type = " + type + "\n");
         if (defaultValue != null) {
             sb.append(prefix + "defaultValue = " + defaultValue + "\n");
@@ -135,16 +136,17 @@ public String toString(String prefix) {
         return sb.toString();
     }
 
-    public static Builder builder(String sourceClass, String sourceName, SourceType sourceType, ResolvedType type) {
-        return new Builder(sourceClass, sourceName, sourceType, type);
+    public static Builder builder(String sourceType, String sourceElementName, SourceElementType sourceElementType,
+            ResolvedType type) {
+        return new Builder(sourceType, sourceElementName, sourceElementType, type);
     }
 
     public static class Builder {
 
         private String name;
-        private final String sourceClass;
-        private final String sourceName;
-        private final SourceType sourceType;
+        private final String sourceType;
+        private final String sourceElementName;
+        private final SourceElementType sourceElementType;
         private final ResolvedType type;
         private String defaultValue;
         private String defaultValueForDoc;
@@ -156,10 +158,10 @@ public static class Builder {
         private boolean section = false;
         private boolean sectionGenerated = false;
 
-        public Builder(String sourceClass, String sourceName, SourceType sourceType, ResolvedType type) {
-            this.sourceClass = sourceClass;
-            this.sourceName = sourceName;
+        public Builder(String sourceType, String sourceElementName, SourceElementType sourceElementType, ResolvedType type) {
             this.sourceType = sourceType;
+            this.sourceElementName = sourceElementName;
+            this.sourceElementType = sourceElementType;
             this.type = type;
         }
 
@@ -217,7 +219,8 @@ public DiscoveryConfigProperty build() {
                 defaultValue = TypeUtil.normalizeDurationValue(defaultValue);
             }
 
-            return new DiscoveryConfigProperty(name, sourceClass, sourceName, sourceType, defaultValue, defaultValueForDoc,
+            return new DiscoveryConfigProperty(name, sourceType, sourceElementName, sourceElementType, defaultValue,
+                    defaultValueForDoc,
                     deprecation, mapKey, unnamedMapKey, type, converted, enforceHyphenateEnumValue, section, sectionGenerated);
         }
     }

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/discovery/DiscoveryRootElement.java

@@ -38,7 +38,7 @@ public String getQualifiedName() {
     }
 
     public void addProperty(DiscoveryConfigProperty discoveryConfigProperty) {
-        properties.put(discoveryConfigProperty.getSourceName(), discoveryConfigProperty);
+        properties.put(discoveryConfigProperty.getSourceElementName(), discoveryConfigProperty);
     }
 
     public Map<String, DiscoveryConfigProperty> getProperties() {

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/merger/ModelMerger.java

@@ -43,12 +43,29 @@ public static MergedModel mergeModel(List<Path> buildOutputDirectories) {
      * target/ directories found in the parent directory scanned).
      */
     public static MergedModel mergeModel(JavadocRepository javadocRepository, List<Path> buildOutputDirectories) {
+        return mergeModel(javadocRepository, buildOutputDirectories, false);
+    }
+
+    /**
+     * Merge all the resolved models obtained from a list of build output directories (e.g. in the case of Maven, the list of
+     * target/ directories found in the parent directory scanned).
+     */
+    public static MergedModel mergeModel(List<Path> buildOutputDirectories, boolean mergeCommonOrInternalExtensions) {
+        return mergeModel(null, buildOutputDirectories, mergeCommonOrInternalExtensions);
+    }
+
+    /**
+     * Merge all the resolved models obtained from a list of build output directories (e.g. in the case of Maven, the list of
+     * target/ directories found in the parent directory scanned).
+     */
+    public static MergedModel mergeModel(JavadocRepository javadocRepository, List<Path> buildOutputDirectories,
+            boolean mergeCommonOrInternalExtensions) {
         // keyed on extension and then top level prefix
         Map<Extension, Map<ConfigRootKey, ConfigRoot>> configRoots = new HashMap<>();
         // keyed on file name
         Map<String, ConfigRoot> configRootsInSpecificFile = new TreeMap<>();
         // keyed on extension
-        Map<Extension, List<ConfigSection>> generatedConfigSections = new TreeMap<>();
+        Map<Extension, List<ConfigSection>> generatedConfigSections = new HashMap<>();
 
         for (Path buildOutputDirectory : buildOutputDirectories) {
             Path resolvedModelPath = buildOutputDirectory.resolve(Outputs.QUARKUS_CONFIG_DOC_MODEL);
@@ -85,7 +102,8 @@ public static MergedModel mergeModel(JavadocRepository javadocRepository, List<P
                         continue;
                     }
 
-                    Map<ConfigRootKey, ConfigRoot> extensionConfigRoots = configRoots.computeIfAbsent(configRoot.getExtension(),
+                    Map<ConfigRootKey, ConfigRoot> extensionConfigRoots = configRoots.computeIfAbsent(
+                            normalizeExtension(configRoot.getExtension(), mergeCommonOrInternalExtensions),
                             e -> new TreeMap<>());
 
                     ConfigRootKey configRootKey = getConfigRootKey(javadocRepository, configRoot);
@@ -102,6 +120,7 @@ public static MergedModel mergeModel(JavadocRepository javadocRepository, List<P
             }
         }
 
+        // note that the configRoots are now sorted by extension name
         configRoots = retainBestExtensionKey(configRoots);
 
         for (Entry<Extension, Map<ConfigRootKey, ConfigRoot>> extensionConfigRootsEntry : configRoots.entrySet()) {
@@ -116,6 +135,18 @@ public static MergedModel mergeModel(JavadocRepository javadocRepository, List<P
         return new MergedModel(configRoots, configRootsInSpecificFile, generatedConfigSections);
     }
 
+    private static Extension normalizeExtension(Extension extension, boolean mergeCommonOrInternalExtensions) {
+        if (!mergeCommonOrInternalExtensions) {
+            return extension;
+        }
+
+        if (extension.commonOrInternal()) {
+            return extension.normalizeCommonOrInternal();
+        }
+
+        return extension;
+    }
+
     private static Map<Extension, Map<ConfigRootKey, ConfigRoot>> retainBestExtensionKey(
             Map<Extension, Map<ConfigRootKey, ConfigRoot>> configRoots) {
         return configRoots.entrySet().stream().collect(Collectors.toMap(e -> {

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

@@ -7,35 +7,36 @@
 public sealed abstract class AbstractConfigItem implements Comparable<AbstractConfigItem>
         permits ConfigProperty, ConfigSection {
 
-    protected final String sourceClass;
-    protected final String sourceName;
-    protected final SourceType sourceType;
+    protected final String sourceType;
+    protected final String sourceElementName;
+    protected final SourceElementType sourceElementType;
     protected final Path path;
 
     protected final String type;
 
     protected Deprecation deprecation;
 
-    public AbstractConfigItem(String sourceClass, String sourceName, SourceType sourceType, Path path, String type,
+    public AbstractConfigItem(String sourceType, String sourceElementName, SourceElementType sourceElementType, Path path,
+            String type,
             Deprecation deprecation) {
-        this.sourceClass = sourceClass;
-        this.sourceName = sourceName;
         this.sourceType = sourceType;
+        this.sourceElementName = sourceElementName;
+        this.sourceElementType = sourceElementType;
         this.path = path;
         this.type = type;
         this.deprecation = deprecation;
     }
 
-    public String getSourceClass() {
-        return sourceClass;
+    public String getSourceType() {
+        return sourceType;
     }
 
-    public String getSourceName() {
-        return sourceName;
+    public String getSourceElementName() {
+        return sourceElementName;
     }
 
-    public SourceType getSourceType() {
-        return sourceType;
+    public SourceElementType getSourceElementType() {
+        return sourceElementType;
     }
 
     public Path getPath() {

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

@@ -29,14 +29,14 @@ public final class ConfigProperty extends AbstractConfigItem {
 
     private final String javadocSiteLink;
 
-    public ConfigProperty(ConfigPhase phase, String sourceClass, String sourceName, SourceType sourceType, PropertyPath path,
-            List<PropertyPath> additionalPaths, String type, String typeDescription, boolean map, boolean list,
-            boolean optional,
+    public ConfigProperty(ConfigPhase phase, String sourceType, String sourceElementName, SourceElementType sourceElementType,
+            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,
             Deprecation deprecation) {
-        super(sourceClass, sourceName, sourceType, path, type, deprecation);
+        super(sourceType, sourceElementName, sourceElementType, path, type, deprecation);
         this.phase = phase;
         this.additionalPaths = additionalPaths != null ? Collections.unmodifiableList(additionalPaths) : List.of();
         this.typeDescription = typeDescription;

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

@@ -11,9 +11,9 @@ 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, SourceType sourceType, SectionPath path, String type, int level,
-            boolean generated, Deprecation deprecation) {
-        super(sourceClass, sourceName, sourceType, path, type, deprecation);
+    public ConfigSection(String sourceType, String sourceElementName, SourceElementType sourceElementType, SectionPath path,
+            String type, int level, boolean generated, Deprecation deprecation) {
+        super(sourceType, sourceElementName, sourceElementType, path, type, deprecation);
         this.generated = generated;
         this.level = level;
     }

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

@@ -5,10 +5,24 @@
 import com.fasterxml.jackson.annotation.JsonIgnore;
 
 public record Extension(String groupId, String artifactId, String name,
-        NameSource nameSource, boolean detected) implements Comparable<Extension> {
+        NameSource nameSource, boolean commonOrInternal, String guideUrl, boolean detected) implements Comparable<Extension> {
+
+    private static final String ARTIFACT_COMMON_SUFFIX = "-common";
+    private static final String ARTIFACT_INTERNAL_SUFFIX = "-internal";
+
+    public static Extension of(String groupId, String artifactId, String name,
+            NameSource nameSource, String guideUrl) {
+        boolean commonOrInternal = artifactId.endsWith(ARTIFACT_COMMON_SUFFIX) || artifactId.endsWith(ARTIFACT_INTERNAL_SUFFIX);
+        if (commonOrInternal) {
+            nameSource = nameSource == NameSource.EXTENSION_METADATA ? NameSource.EXTENSION_METADATA_COMMON_INTERNAL
+                    : (nameSource == NameSource.POM_XML ? NameSource.POM_XML_COMMON_INTERNAL : nameSource);
+        }
+
+        return new Extension(groupId, artifactId, name, nameSource, commonOrInternal, guideUrl, true);
+    }
 
     public static Extension createNotDetected() {
-        return new Extension("not.detected", "not.detected", "Not detected", NameSource.NONE, false);
+        return new Extension("not.detected", "not.detected", "Not detected", NameSource.NONE, false, null, false);
     }
 
     @Override
@@ -50,6 +64,27 @@ public boolean splitOnConfigRootDescription() {
         return "io.quarkus".equals(groupId) && "quarkus-core".equals(artifactId);
     }
 
+    @JsonIgnore
+    public Extension normalizeCommonOrInternal() {
+        if (!commonOrInternal()) {
+            return this;
+        }
+
+        String normalizedArtifactId = artifactId;
+        if (artifactId.endsWith(ARTIFACT_COMMON_SUFFIX)) {
+            normalizedArtifactId = artifactId.substring(0, artifactId.length() - ARTIFACT_COMMON_SUFFIX.length());
+        }
+        if (artifactId.endsWith(ARTIFACT_INTERNAL_SUFFIX)) {
+            normalizedArtifactId = artifactId.substring(0, artifactId.length() - ARTIFACT_INTERNAL_SUFFIX.length());
+        }
+
+        if (normalizedArtifactId.equals(artifactId)) {
+            return this;
+        }
+
+        return new Extension(groupId, normalizedArtifactId, name, nameSource, commonOrInternal, null, detected);
+    }
+
     @Override
     public int compareTo(Extension other) {
         if (name != null && other.name != null) {

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/SourceType.java → core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/SourceElementType.java

@@ -1,6 +1,6 @@
 package io.quarkus.annotation.processor.documentation.config.model;
 
-public enum SourceType {
+public enum SourceElementType {
 
     METHOD,
     FIELD;

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/resolver/ConfigResolver.java

@@ -134,8 +134,8 @@ private void resolveProperty(ConfigRoot configRoot, Map<String, ConfigSection> e
                 if (configSection != null) {
                     configSection.appendState(discoveryConfigProperty.isSectionGenerated(), deprecation);
                 } else {
-                    configSection = new ConfigSection(discoveryConfigProperty.getSourceClass(),
-                            discoveryConfigProperty.getSourceName(), discoveryConfigProperty.getSourceType(),
+                    configSection = new ConfigSection(discoveryConfigProperty.getSourceType(),
+                            discoveryConfigProperty.getSourceElementName(), discoveryConfigProperty.getSourceElementType(),
                             new SectionPath(path), typeQualifiedName,
                             context.getSectionLevel(), discoveryConfigProperty.isSectionGenerated(), deprecation);
                     context.getItemCollection().addItem(configSection);
@@ -202,9 +202,9 @@ private void resolveProperty(ConfigRoot configRoot, Map<String, ConfigSection> e
 
             // this is a standard property
             ConfigProperty configProperty = new ConfigProperty(phase,
-                    discoveryConfigProperty.getSourceClass(),
-                    discoveryConfigProperty.getSourceName(),
                     discoveryConfigProperty.getSourceType(),
+                    discoveryConfigProperty.getSourceElementName(),
+                    discoveryConfigProperty.getSourceElementType(),
                     propertyPath, additionalPropertyPaths,
                     typeQualifiedName, typeSimplifiedName,
                     discoveryConfigProperty.getType().isMap(), discoveryConfigProperty.getType().isList(),

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/scanner/AbstractConfigListener.java

@@ -67,7 +67,7 @@ public void onResolvedEnum(TypeElement enumTypeElement) {
     }
 
     protected void handleCommonPropertyAnnotations(DiscoveryConfigProperty.Builder builder,
-            Map<String, AnnotationMirror> propertyAnnotations, ResolvedType resolvedType, String sourceName) {
+            Map<String, AnnotationMirror> propertyAnnotations, ResolvedType resolvedType, String sourceElementName) {
 
         AnnotationMirror deprecatedAnnotation = propertyAnnotations.get(Deprecated.class.getName());
         if (deprecatedAnnotation != null) {