Improve documentation of ORM 5.6 compatibility switch

* Move it to the "Database related configuration" section
* Make sure that enum values are rendered correctly

Author: yrodiere

core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java

@@ -60,6 +60,7 @@ final public class Constants {
     public static final String ANNOTATION_CONFIG_GROUP = "io.quarkus.runtime.annotations.ConfigGroup";
     public static final String ANNOTATION_CONFIG_DOC_MAP_KEY = "io.quarkus.runtime.annotations.ConfigDocMapKey";
     public static final String ANNOTATION_CONFIG_DOC_SECTION = "io.quarkus.runtime.annotations.ConfigDocSection";
+    public static final String ANNOTATION_CONFIG_DOC_ENUM_VALUE = "io.quarkus.runtime.annotations.ConfigDocEnumValue";
 
     public static final String ANNOTATION_CONFIG_WITH_NAME = "io.smallrye.config.WithName";
     public static final String ANNOTATION_CONFIG_WITH_DEFAULT = "io.smallrye.config.WithDefault";

core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java

@@ -1,5 +1,6 @@
 package io.quarkus.annotation.processor.generate_doc;
 
+import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_DOC_ENUM_VALUE;
 import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_DOC_MAP_KEY;
 import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_DOC_SECTION;
 import static io.quarkus.annotation.processor.Constants.ANNOTATION_CONFIG_ITEM;
@@ -435,7 +436,12 @@ private List<String> extractEnumValues(TypeMirror realTypeMirror, boolean useHyp
                 final String constantJavaDocKey = javaDocKey + DOT + enumValue;
                 final String rawJavaDoc = javaDocProperties.getProperty(constantJavaDocKey);
 
-                enumValue = useHyphenatedEnumValue ? hyphenateEnumValue(enumValue) : enumValue;
+                String explicitEnumValueName = extractEnumValueName(field);
+                if (explicitEnumValueName != null) {
+                    enumValue = explicitEnumValueName;
+                } else {
+                    enumValue = useHyphenatedEnumValue ? hyphenateEnumValue(enumValue) : enumValue;
+                }
                 if (rawJavaDoc != null && !rawJavaDoc.isBlank()) {
                     // Show enum constant description as a Tooltip
                     String javaDoc = enumJavaDocParser.parseConfigDescription(rawJavaDoc);
@@ -450,6 +456,22 @@ private List<String> extractEnumValues(TypeMirror realTypeMirror, boolean useHyp
         return acceptedValues;
     }
 
+    private String extractEnumValueName(Element enumField) {
+        for (AnnotationMirror annotationMirror : enumField.getAnnotationMirrors()) {
+            String annotationName = annotationMirror.getAnnotationType().toString();
+            if (annotationName.equals(ANNOTATION_CONFIG_DOC_ENUM_VALUE)) {
+                for (var entry : annotationMirror.getElementValues().entrySet()) {
+                    var key = entry.getKey().toString();
+                    var value = entry.getValue().getValue();
+                    if ("value()".equals(key)) {
+                        return value.toString();
+                    }
+                }
+            }
+        }
+        return null;
+    }
+
     private boolean isEnumType(TypeMirror realTypeMirror) {
         return realTypeMirror instanceof DeclaredType
                 && ((DeclaredType) realTypeMirror).asElement().getKind() == ElementKind.ENUM;

core/runtime/src/main/java/io/quarkus/runtime/annotations/ConfigDocEnumValue.java

@@ -0,0 +1,27 @@
+package io.quarkus.runtime.annotations;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * A way to explicitly customize the string displayed in the documentation
+ * when listing accepted values for an enum.
+ * <p>
+ * Only works when applied to enum values.
+ */
+@Retention(RUNTIME)
+@Target({ FIELD })
+@Documented
+public @interface ConfigDocEnumValue {
+
+    /**
+     * @return The string displayed in the documentation for this value
+     *         when listing accepted values for a configuration property of the relevant enum type.
+     */
+    String value();
+
+}

extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmConfig.java

@@ -29,31 +29,11 @@ public class HibernateOrmConfig {
     public boolean enabled;
 
     /**
-     * When set, attempts to exchange data with the database
-     * as the given version of Hibernate ORM would have,
-     * *on a best-effort basis*.
-     *
-     * Please note:
-     *
-     * * schema validation may still fail in some cases:
-     * this attempts to make Hibernate ORM 6+ behave correctly at runtime,
-     * but it may still expect a different (but runtime-compatible) schema.
-     * * robust test suites are still useful and recommended:
-     * you should still check that your application behaves as intended with your legacy schema.
-     * * this feature is inherently unstable:
-     * some aspects of it may stop working in future versions of Quarkus,
-     * and older versions will be dropped as Hibernate ORM changes pile up
-     * and support for those older versions becomes too unreliable.
-     * * you should still plan a migration of your schema to a newer version of Hibernate ORM.
-     * For help with migration, refer to
-     * link:https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0:-Hibernate-ORM-5-to-6-migration[the Quarkus 3
-     * migration guide from Hibernate ORM 5 to 6].
-     *
-     * @asciidoclet
+     * Database related configuration.
      */
-    @ConfigItem(name = "database.orm-compatibility.version", defaultValue = "LATEST")
-    @ConvertWith(DatabaseOrmCompatibilityVersion.Converter.class)
-    public DatabaseOrmCompatibilityVersion databaseOrmCompatibilityVersion;
+    @ConfigItem
+    @ConfigDocSection
+    public HibernateOrmConfigDatabase database;
 
     /**
      * Configuration for the default persistence unit.
@@ -159,4 +139,35 @@ public boolean isAnyPropertySet() {
             return bindParam || bindParameters;
         }
     }
+
+    @ConfigGroup
+    public static class HibernateOrmConfigDatabase {
+        /**
+         * When set, attempts to exchange data with the database
+         * as the given version of Hibernate ORM would have,
+         * *on a best-effort basis*.
+         *
+         * Please note:
+         *
+         * * schema validation may still fail in some cases:
+         * this attempts to make Hibernate ORM 6+ behave correctly at runtime,
+         * but it may still expect a different (but runtime-compatible) schema.
+         * * robust test suites are still useful and recommended:
+         * you should still check that your application behaves as intended with your legacy schema.
+         * * this feature is inherently unstable:
+         * some aspects of it may stop working in future versions of Quarkus,
+         * and older versions will be dropped as Hibernate ORM changes pile up
+         * and support for those older versions becomes too unreliable.
+         * * you should still plan a migration of your schema to a newer version of Hibernate ORM.
+         * For help with migration, refer to
+         * link:https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0:-Hibernate-ORM-5-to-6-migration[the Quarkus 3
+         * migration guide from Hibernate ORM 5 to 6].
+         *
+         * @asciidoclet
+         */
+        @ConfigItem(name = "orm-compatibility.version", defaultValue = "latest")
+        @ConvertWith(DatabaseOrmCompatibilityVersion.Converter.class)
+        public DatabaseOrmCompatibilityVersion ormCompatibilityVersion;
+    }
+
 }

extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmProcessor.java

@@ -395,7 +395,7 @@ public void configurationDescriptorBuilding(
                             null,
                             jpaModel.getXmlMappings(persistenceXmlDescriptorBuildItem.getDescriptor().getName()),
                             Collections.emptyMap(),
-                            hibernateOrmConfig.databaseOrmCompatibilityVersion,
+                            hibernateOrmConfig.database.ormCompatibilityVersion,
                             false, true));
         }
 
@@ -1205,7 +1205,7 @@ private static void producePersistenceUnitDescriptorFromConfig(
                         persistenceUnitConfig.multitenantSchemaDatasource.orElse(null),
                         xmlMappings,
                         persistenceUnitConfig.unsupportedProperties,
-                        hibernateOrmConfig.databaseOrmCompatibilityVersion,
+                        hibernateOrmConfig.database.ormCompatibilityVersion,
                         false, false));
     }
 

extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/config/DatabaseOrmCompatibilityVersion.java

@@ -10,8 +10,17 @@
 import org.hibernate.cfg.AvailableSettings;
 
 import io.quarkus.datasource.common.runtime.DatabaseKind;
+import io.quarkus.runtime.annotations.ConfigDocEnumValue;
 
 public enum DatabaseOrmCompatibilityVersion {
+    /**
+     * **Best-effort** compatibility with a database schema and data
+     * meant for Hibernate ORM 5.6,
+     * even though the version of Hibernate ORM shipped with Quarkus is different.
+     *
+     * @asciidoclet
+     */
+    @ConfigDocEnumValue("5.6")
     V5_6("5.6") {
         @Override
         public Map<String, String> settings(Optional<String> dbKind) {
@@ -43,6 +52,15 @@ public Map<String, String> settings(Optional<String> dbKind) {
             return result;
         }
     },
+    /**
+     * No particular effort on compatibility:
+     * just assume the database schema and data are compatible
+     * with the "latest" version of Hibernate ORM,
+     * i.e. the version shipped with Quarkus.
+     *
+     * @asciidoclet
+     */
+    @ConfigDocEnumValue("latest")
     LATEST("latest") {
         @Override
         public Map<String, String> settings(Optional<String> dbKind) {
@@ -62,6 +80,12 @@ private static boolean usedToSupportUuid(String dbKind) {
         this.externalRepresentation = externalRepresentation;
     }
 
+    @Override
+    public String toString() {
+        // Necessary for proper rendering in the documentation
+        return externalRepresentation;
+    }
+
     public abstract Map<String, String> settings(Optional<String> dbKind);
 
     public static class Converter

extensions/hibernate-reactive/deployment/src/main/java/io/quarkus/hibernate/reactive/deployment/HibernateReactiveProcessor.java

@@ -166,7 +166,7 @@ public void buildReactivePersistenceUnit(
                     PersistenceUnitUtil.DEFAULT_PERSISTENCE_UNIT_NAME, dbKindOptional,
                     jpaModel.getXmlMappings(reactivePU.getName()),
                     persistenceUnitConfig.unsupportedProperties,
-                    hibernateOrmConfig.databaseOrmCompatibilityVersion,
+                    hibernateOrmConfig.database.ormCompatibilityVersion,
                     true, false));
         }