PartitionKey jdoc and fix to DDL formatting

hibernate-core/src/main/java/org/hibernate/annotations/PartitionKey.java

@@ -12,12 +12,50 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Identifies a field of an entity that holds the partition key of a table.
+ * Identifies a field of an entity that holds the
+ * partition key of a table mapped by the entity
+ * class.
+ * <p>
+ * If the partition key forms part of the unique
+ * {@linkplain jakarta.persistence.Id identifier}
+ * of the entity, this annotation is optional but
+ * may still be applied for documentation purposes.
+ * <p>
+ * On the other hand, if the partition key is not
+ * part of the identifier, use of this annotation
+ * may improve the performance of SQL {@code update}
+ * and {@code delete} statements.
+ * <p>
+ * <pre>
+ * &#064;Entity
+ * &#064;Table(name  = "partitioned_table",
+ *     options =
+ *         """
+ *         partition by range (pid) (
+ *             partition p1 values less than (1000),
+ *             partition p2 values less than (2000)
+ *         )
+ *         """)
+ * class Partitioned {
+ *     &#064;Id &#064;GeneratedValue Long id;
+ *     &#064;PartitionKey Long pid;
+ *     String text;
+ * }
+ * </pre>
+ * Many databases are not able to maintain a unique
+ * key constraint across multiple partitions unless
+ * the unique key contains the partition key column.
+ * On these databases, the column mapped by a field
+ * annotated {@code @PartitionKey} is automatically
+ * added to the generated primary key constraint.
+ * In this case, the database is not able to enforce
+ * uniqueness of the identifier value, and care must
+ * be taken to ensure that the identifier is unique
+ * across entity instances.
  *
  * @since 6.2
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface PartitionKey {
-
 }

hibernate-core/src/main/java/org/hibernate/engine/jdbc/internal/DDLFormatterImpl.java

@@ -58,7 +58,9 @@ else if ( lowerCaseSql.startsWith( "comment on" ) ) {
 
 	private String formatCommentOn(String sql) {
 		final StringBuilder result = new StringBuilder( 60 ).append( INITIAL_LINE );
-		final StringTokenizer tokens = new StringTokenizer( sql, " '[]\"", true );
+		final StringTokenizer tokens =
+				new StringTokenizer( sql.replace('\n',' '),
+						" '[]\"", true );
 
 		boolean quoted = false;
 		while ( tokens.hasMoreTokens() ) {
@@ -79,7 +81,9 @@ else if ( !quoted ) {
 
 	private String formatAlterTable(String sql) {
 		final StringBuilder result = new StringBuilder( 60 ).append( INITIAL_LINE );
-		final StringTokenizer tokens = new StringTokenizer( sql, " (,)'[]\"", true );
+		final StringTokenizer tokens =
+				new StringTokenizer( sql.replace('\n',' '),
+						" (,)'[]\"", true );
 
 		boolean first = true;
 		boolean quoted = false;
@@ -102,7 +106,9 @@ else if ( !quoted ) {
 
 	private String formatCreateTable(String sql) {
 		final StringBuilder result = new StringBuilder( 60 ).append( INITIAL_LINE );
-		final StringTokenizer tokens = new StringTokenizer( sql, "(,)'[]\"", true );
+		final StringTokenizer tokens =
+				new StringTokenizer( sql.replace('\n',' '),
+						"(,)'[]\"", true );
 
 		int depth = 0;
 		boolean quoted = false;