Display deprecated properties in documentation

gsmet · gsmet · commit d5d425bd816d · 2025-11-21T11:47:20.000+01:00
Fixes #51101
diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/discovery/DiscoveryConfigProperty.java b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/discovery/DiscoveryConfigProperty.java
@@ -181,7 +181,7 @@ public Builder defaultValueForDoc(String defaultValueForDoc) {
         }
 
         public Builder deprecated(String since, String replacement, String reason) {
-            this.deprecation = new Deprecation(since, replacement, reason);
+            this.deprecation = new Deprecation(since, replacement);
             return this;
         }
 
diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigItemCollection.java b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigItemCollection.java
@@ -8,26 +8,44 @@ public interface ConfigItemCollection {
 
     List<AbstractConfigItem> getItems();
 
+    @JsonIgnore
+    default List<ConfigProperty> getProperties() {
+        return getItems().stream()
+                .filter(i -> i instanceof ConfigProperty)
+                .map(ConfigProperty.class::cast)
+                .toList();
+    }
+
+    @JsonIgnore
+    default List<ConfigSection> getSections() {
+        return getItems().stream()
+                .filter(i -> i instanceof ConfigSection)
+                .map(ConfigSection.class::cast)
+                .toList();
+    }
+
     @JsonIgnore
     default List<AbstractConfigItem> getNonDeprecatedItems() {
         return getItems().stream()
                 .filter(i -> (i instanceof ConfigSection)
-                        ? !i.isDeprecated() && ((ConfigSection) i).getNonDeprecatedItems().size() > 0
+                        ? !i.isDeprecated() && !((ConfigSection) i).getNonDeprecatedItems().isEmpty()
                         : !i.isDeprecated())
                 .toList();
     }
 
     @JsonIgnore
-    default List<AbstractConfigItem> getNonDeprecatedProperties() {
+    default List<ConfigProperty> getNonDeprecatedProperties() {
         return getItems().stream()
                 .filter(i -> i instanceof ConfigProperty && !i.isDeprecated())
+                .map(ConfigProperty.class::cast)
                 .toList();
     }
 
     @JsonIgnore
-    default List<AbstractConfigItem> getNonDeprecatedSections() {
+    default List<ConfigSection> getNonDeprecatedSections() {
         return getItems().stream()
                 .filter(i -> i instanceof ConfigSection && !i.isDeprecated())
+                .map(ConfigSection.class::cast)
                 .toList();
     }
 
diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigProperty.java b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigProperty.java
@@ -137,6 +137,13 @@ public int compareTo(AbstractConfigItem o) {
 
         ConfigProperty other = (ConfigProperty) o;
 
+        // let's put the deprecated properties last
+        if (isDeprecated() && !other.isDeprecated()) {
+            return 1;
+        } else if (!isDeprecated() && other.isDeprecated()) {
+            return -1;
+        }
+
         if (isWithinMap()) {
             if (other.isWithinMap()) {
                 return ConfigPhase.COMPARATOR.compare(phase, other.getPhase());
diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/Deprecation.java b/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/Deprecation.java
@@ -1,5 +1,5 @@
 package io.quarkus.annotation.processor.documentation.config.model;
 
-public record Deprecation(String since, String replacement, String reason) {
+public record Deprecation(String since, String replacement) {
 
 }
diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java
@@ -382,6 +382,14 @@ private static Engine initializeQuteEngine(Formatter formatter, Format format, S
                                         (Extension) ctx.evaluate(ctx.getParams().get(0)).toCompletableFuture().join(),
                                         (Context) ctx.evaluate(ctx.getParams().get(1)).toCompletableFuture().join()))
                         .build())
+                .addValueResolver(ValueResolver.builder()
+                        .applyToBaseClass(ConfigProperty.class)
+                        .applyToName("formatDeprecatedReason")
+                        .applyToParameters(2)
+                        .resolveSync(ctx -> formatter.formatDeprecatedReason((ConfigProperty) ctx.getBase(),
+                                (Extension) ctx.evaluate(ctx.getParams().get(0)).toCompletableFuture().join(),
+                                (Context) ctx.evaluate(ctx.getParams().get(1)).toCompletableFuture().join()))
+                        .build())
                 .addValueResolver(ValueResolver.builder()
                         .applyToBaseClass(ConfigProperty.class)
                         .applyToName("formatDefaultValue")
diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AbstractFormatter.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AbstractFormatter.java
@@ -65,6 +65,28 @@ public String formatDescription(ConfigProperty configProperty) {
         return description + "\n\n";
     }
 
+    @Override
+    public String formatDeprecatedReason(ConfigProperty configProperty, Extension extension, Context context) {
+        Optional<JavadocElement> javadocElement = javadocRepository.getElement(configProperty.getSourceType(),
+                configProperty.getSourceElementName());
+
+        if (javadocElement.isEmpty()) {
+            return null;
+        }
+
+        String deprecatedReason = JavadocTransformer.transform(javadocElement.get().deprecated(), JavadocFormat.JAVADOC,
+                javadocFormat());
+        if (deprecatedReason == null || deprecatedReason.isBlank()) {
+            return null;
+        }
+
+        if (deprecatedReason.endsWith(".")) {
+            return deprecatedReason.substring(0, deprecatedReason.length() - 1);
+        }
+
+        return deprecatedReason;
+    }
+
     @Override
     public String formatTypeDescription(ConfigProperty configProperty, Context context) {
         String typeContent = "";
diff --git a/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/Formatter.java b/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/Formatter.java
@@ -17,6 +17,8 @@ default String formatDescription(ConfigProperty configProperty, Extension extens
         return formatDescription(configProperty);
     }
 
+    String formatDeprecatedReason(ConfigProperty configProperty, Extension extension, Context context);
+
     String formatTypeDescription(ConfigProperty configProperty, Context context);
 
     String formatDefaultValue(ConfigProperty configProperty);
diff --git a/devtools/config-doc-maven-plugin/src/main/resources/templates/asciidoc/default/allConfig.qute.adoc b/devtools/config-doc-maven-plugin/src/main/resources/templates/asciidoc/default/allConfig.qute.adoc
@@ -9,7 +9,6 @@ h|Type
 h|Default
 
 {#for configRootEntry in extensionConfigRootsEntry.value}
-{#if configRootEntry.value.nonDeprecatedItems}
 {#let displayConfigRootDescription=configRootEntry.key.displayConfigRootDescription(extensionConfigRootsEntry.value.size)}
 {#if displayConfigRootDescription}
 h|[.configroot-name]##{configRootEntry.key.description.escapeCellContent}##
@@ -18,18 +17,15 @@ h|Default
 
 {/if}
 {#for item in configRootEntry.value.items}
-{#if !item.deprecated}
 {#if item.isSection}
 {#configSection context=context configSection=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=displayConfigRootDescription /}
 
 {#else}
 {#configProperty context=context configProperty=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix /}
 
-{/if}
 {/if}
 {/for}
 {/let}
-{/if}
 {/for}
 {/for}
 |===
diff --git a/devtools/config-doc-maven-plugin/src/main/resources/templates/asciidoc/default/configReference.qute.adoc b/devtools/config-doc-maven-plugin/src/main/resources/templates/asciidoc/default/configReference.qute.adoc
@@ -7,7 +7,7 @@ h|[.header-title]##Configuration property##
 h|Type
 h|Default
 
-{#for item in configItemCollection.nonDeprecatedItems}
+{#for item in configItemCollection.items}
 {#if item.isSection}
 {#configSection context=context configSection=item extension=extension additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=false /}
 
diff --git a/devtools/config-doc-maven-plugin/src/main/resources/templates/asciidoc/default/tags/configProperty.qute.adoc b/devtools/config-doc-maven-plugin/src/main/resources/templates/asciidoc/default/tags/configProperty.qute.adoc
@@ -1,14 +1,20 @@
-a|{#if configProperty.phase.fixedAtBuildTime}icon:lock[title=Fixed at build time]{/if} [[{configProperty.toAnchor(extension, additionalAnchorPrefix)}]] [.property-path]##link:#{configProperty.toAnchor(extension, additionalAnchorPrefix)}[`{configProperty.path.property}`]##
+a|{#if configProperty.phase.fixedAtBuildTime}icon:lock[title=Fixed at build time]{/if} [[{configProperty.toAnchor(extension, additionalAnchorPrefix)}]] [.property-path]##link:#{configProperty.toAnchor(extension, additionalAnchorPrefix)}[{#if configProperty.deprecated}[.line-through]#{/if}`{configProperty.path.property}`{#if configProperty.deprecated}#{/if}]##
 {#propertyCopyButton configProperty.path.property /}
 
 {#for additionalPath in configProperty.additionalPaths}
 
-`{additionalPath.property}`
+{#if configProperty.deprecated}[.line-through]#{/if}`{additionalPath.property}`{#if configProperty.deprecated}#{/if}
 {#propertyCopyButton additionalPath.property /}
 {/for}
 
 [.description]
 --
+{#if configProperty.deprecation}
+{#let deprecatedReason=configProperty.formatDeprecatedReason(extension, context)}
+_This property is deprecated{#if configProperty.deprecation.since} since `{configProperty.deprecation.since}`{/if}{#if deprecatedReason}: {deprecatedReason}{/if}._
+
+{/let}
+{/if}
 {configProperty.formatDescription(extension, context).escapeCellContent.or("")}
 {#envVar configProperty /}
 --
diff --git a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java
@@ -4,6 +4,7 @@
 import java.util.Optional;
 
 import io.quarkus.datasource.common.runtime.DataSourceUtil;
+import io.quarkus.runtime.annotations.ConfigDocIgnore;
 import io.quarkus.runtime.annotations.ConfigDocMapKey;
 import io.quarkus.runtime.annotations.ConfigPhase;
 import io.quarkus.runtime.annotations.ConfigRoot;
@@ -53,18 +54,14 @@ public interface DataSourcesBuildTimeConfig {
      * Only here to detect configuration errors.
      * <p>
      * This used to be runtime but we don't really care, we just want to catch invalid configurations.
-     *
-     * @deprecated
      */
-    @Deprecated
+    @ConfigDocIgnore
     Optional<String> url();
 
     /**
      * Only here to detect configuration errors.
-     *
-     * @deprecated
      */
-    @Deprecated
+    @ConfigDocIgnore
     Optional<String> driver();
 
     default boolean hasNamedDataSources() {
diff --git a/extensions/micrometer/runtime/src/main/java/io/quarkus/micrometer/runtime/config/runtime/VertxConfig.java b/extensions/micrometer/runtime/src/main/java/io/quarkus/micrometer/runtime/config/runtime/VertxConfig.java
@@ -10,7 +10,25 @@
 @ConfigMapping(prefix = "quarkus.micrometer.binder.vertx")
 @ConfigRoot(phase = ConfigPhase.RUN_TIME)
 public interface VertxConfig {
+
     /**
+     * Comma-separated list of regular expressions used to specify uri
+     * labels in http metrics.
+     *
+     * Vertx instrumentation will attempt to transform parameterized
+     * resource paths, `/item/123`, into a generic form, `/item/{id}`,
+     * to reduce the cardinality of uri label values.
+     *
+     * Patterns specified here will take precedence over those computed
+     * values.
+     *
+     * For example, if `/item/\\\\d+=/item/custom` or
+     * `/item/[0-9]+=/item/custom` is specified in this list,
+     * a request to a matching path (`/item/123`) will use the specified
+     * replacement value (`/item/custom`) as the value for the uri label.
+     * Note that backslashes must be double escaped as `\\\\`.
+     *
+     * @asciidoclet
      * @deprecated use {@code quarkus.micrometer.binder.http-server.match-patterns}
      */
     @Deprecated
diff --git a/extensions/redis-client/runtime/src/main/java/io/quarkus/redis/runtime/client/config/RedisClientConfig.java b/extensions/redis-client/runtime/src/main/java/io/quarkus/redis/runtime/client/config/RedisClientConfig.java
@@ -153,6 +153,13 @@ public interface RedisClientConfig {
     Optional<ProtocolVersion> preferredProtocolVersion();
 
     /**
+     * The TTL of the topology cache. A topology cache is used by a clustered Redis client
+     * and a sentinel Redis client to prevent constantly sending topology discovery commands
+     * ({@code CLUSTER SLOTS} or {@code SENTINEL ...}).
+     * <p>
+     * This setting is only meaningful in case of a clustered Redis client and a sentinel
+     * Redis client and has no effect otherwise.
+     *
      * @deprecated use {@code quarkus.redis.topology-cache-ttl}
      */
     @Deprecated(forRemoval = true, since = "3.30")
diff --git a/extensions/vertx/runtime/src/main/java/io/quarkus/vertx/core/runtime/config/VertxConfiguration.java b/extensions/vertx/runtime/src/main/java/io/quarkus/vertx/core/runtime/config/VertxConfiguration.java
@@ -52,6 +52,8 @@ public interface VertxConfiguration {
     Duration warningExceptionTime();
 
     /**
+     * The size of the worker pool size.
+     *
      * @deprecated use {@code quarkus.thread-pool.max-threads} instead
      */
     @WithDefault("${quarkus.thread-pool.max-threads:20}")

Original file line number	Diff line number	Diff line change
`@@ -181,7 +181,7 @@ public Builder defaultValueForDoc(String defaultValueForDoc) {`
`181`	`181`	`}`
`182`	`182`
`183`	`183`	`public Builder deprecated(String since, String replacement, String reason) {`
`184`		`- this.deprecation = new Deprecation(since, replacement, reason);`
	`184`	`+ this.deprecation = new Deprecation(since, replacement);`
`185`	`185`	`return this;`
`186`	`186`	`}`
`187`	`187`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`package io.quarkus.annotation.processor.documentation.config.model;`
`2`	`2`
`3`		`-public record Deprecation(String since, String replacement, String reason) {`
	`3`	`+public record Deprecation(String since, String replacement) {`
`4`	`4`
`5`	`5`	`}`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,8 @@ default String formatDescription(ConfigProperty configProperty, Extension extens`
`17`	`17`	`return formatDescription(configProperty);`
`18`	`18`	`}`
`19`	`19`
	`20`	`+ String formatDeprecatedReason(ConfigProperty configProperty, Extension extension, Context context);`
	`21`	`+`
`20`	`22`	`String formatTypeDescription(ConfigProperty configProperty, Context context);`
`21`	`23`
`22`	`24`	`String formatDefaultValue(ConfigProperty configProperty);`