javadoc around nationalized character support

hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java

@@ -628,11 +628,38 @@ public interface AvailableSettings {
 	String IGNORE_EXPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS = "hibernate.discriminator.ignore_explicit_for_joined";
 
 	/**
-	 * Enables nationalized character support for mappings to {@code VARCHAR} and {@code CLOB}.
+	 * By default, Hibernate maps character data represented by {@link String}s and
+	 * {@link java.sql.Clob}s to the JDBC types {@link java.sql.Types#VARCHAR} and
+	 * {@link java.sql.Types#CLOB}. This setting, when enabled, turns on the use of
+	 * explicit nationalized character support for mappings involving character
+	 * data, specifying that the JDBC types {@link java.sql.Types#NVARCHAR} and
+	 * {@link java.sql.Types#NCLOB} should be used instead.
 	 * <p>
-	 * Default is {@code false}.
+	 * This setting is relevant for use with databases with
+	 * {@linkplain org.hibernate.dialect.NationalizationSupport#EXPLICIT explicit
+	 * nationalization support}, and it is not needed for databases whose native
+	 * {@code varchar} and {@code clob} types support Unicode data. (If you're not
+	 * sure how your database handles Unicode, check out the implementation of
+	 * {@link org.hibernate.dialect.Dialect#getNationalizationSupport()} for its
+	 * SQL dialect.)
+	 * <p>
+	 * Enabling this setting has two effects:
+	 * <ol>
+	 *     <li>when interacting with JDBC, Hibernate uses operations like
+	 *         {@link java.sql.PreparedStatement#setNString(int, String)}
+	 *         {@link java.sql.PreparedStatement#setNClob(int, java.sql.NClob)}
+	 *         to pass character data, and
+	 *     <li>when generating DDL, the schema export tool uses {@code nvarchar}
+	 *         and {@code nclob} as the generated column types when no column
+	 *         type is explicitly specified using
+	 *         {@link jakarta.persistence.Column#columnDefinition()}.
+	 * </ol>
+	 * This setting is <em>disabled</em> by default, and so Unicode character data
+	 * may not be persisted correctly for databases with explicit nationalization
+	 * support.
 	 *
 	 * @see org.hibernate.boot.MetadataBuilder#enableGlobalNationalizedCharacterDataSupport(boolean)
+	 * @see org.hibernate.dialect.NationalizationSupport
 	 */
 	String USE_NATIONALIZED_CHARACTER_DATA = "hibernate.use_nationalized_character_data";
 

hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java

@@ -3531,6 +3531,14 @@ public abstract class Dialect implements ConversionContext {
 		return databaseMetaData != null && databaseMetaData.supportsNamedParameters();
 	}
 
+	/**
+	 * Determines whether this database requires the use
+	 * of explicit nationalized character data types.
+	 * <p>
+	 * That is, whether the use of {@link Types#NCHAR},
+	 * {@link Types#NVARCHAR}, and {@link Types#NCLOB} is
+	 * required for nationalized character data (Unicode).
+	 */
 	public NationalizationSupport getNationalizationSupport() {
 		return NationalizationSupport.EXPLICIT;
 	}

hibernate-core/src/main/java/org/hibernate/dialect/NationalizationSupport.java

@@ -9,25 +9,29 @@ package org.hibernate.dialect;
 import java.sql.Types;
 
 /**
- * Indicates how (if) the underlying database supports the use of nationalized data
+ * Indicates if and how a database supports the use of nationalized
+ * character data (Unicode).
+ *
+ * @see org.hibernate.cfg.AvailableSettings#USE_NATIONALIZED_CHARACTER_DATA
+ * @see Dialect#getNationalizationSupport()
  */
 public enum NationalizationSupport {
 	/**
-	 * The database's CHAR, VARCHAR, LONGVARCHAR and CLOB types
+	 * The {@code CHAR}, {@code VARCHAR}, and {@code CLOB}
-	 * inherently handle nationalized data.  Generally speaking
+	 * types inherently handle nationalized character data.
-	 * this means the database will not have dedicated nationalized
+	 * Usually the database will not even define dedicated
-	 * data types (NCHAR, ...)
+	 * nationalized data types like {@code NVARCHAR}.
 	 */
 	IMPLICIT( Types.CHAR, Types.VARCHAR, Types.LONGVARCHAR, Types.CLOB ),
 	/**
-	 * The database does define/support distinct nationalized
+	 * The database does define and support distinct SQL types
-	 * data types (NCHAR, ...).
+	 * for representing nationalized character data, typically
+	 * named {@code NCHAR}, {@code NVARCHAR}, and {@code NCLOB}.
 	 */
 	EXPLICIT( Types.NCHAR, Types.NVARCHAR, Types.LONGNVARCHAR, Types.NCLOB ),
 	/**
-	 * The database does not define/support distinct nationalized
+	 * The database does not even have support for nationalized
-	 * data types (NCHAR, ...) and its corresponding base data
+	 * character data.
-	 * types (CHAR, ...) do not support nationalized data
 	 */
 	UNSUPPORTED;