improve jdoc of SQM enums

Signed-off-by: Gavin King <gavin@hibernate.org>

hibernate-core/src/main/java/org/hibernate/query/sqm/CastType.java

@@ -8,8 +8,8 @@ package org.hibernate.query.sqm;
  * Defines the set of basic types which should be
  * accepted by the {@code cast()} function on every
  * platform.
- * <p>
- * Note that while almost every database supports
+ *
+ * @implNote While almost every database supports
  * the ANSI {@code cast()} function, the actual type
  * conversions supported vary widely. Therefore, it
  * is sometimes necessary to emulate certain type
@@ -19,6 +19,11 @@ package org.hibernate.query.sqm;
  * type, and so type conversions to and from
  * {@link Boolean} must be emulated.
  *
+ * @apiNote This is an SPI type allowing collaboration
+ * between {@code org.hibernate.dialect} and
+ * {@code org.hibernate.sqm}. It should never occur in
+ * APIs visible to the application program.
+ *
  * @see org.hibernate.dialect.Dialect#castPattern(CastType, CastType)
  *
  * @author Gavin King
@@ -33,16 +38,9 @@ public enum CastType {
 	OTHER;
 
 	public boolean isNumeric() {
-		switch (this) {
-			case INTEGER:
-			case LONG:
-			case INTEGER_BOOLEAN:
-			case FLOAT:
-			case DOUBLE:
-			case FIXED:
-				return true;
-			default:
-				return false;
-		}
+		return switch ( this ) {
+			case INTEGER, LONG, INTEGER_BOOLEAN, FLOAT, DOUBLE, FIXED -> true;
+			default -> false;
+		};
 	}
 }

hibernate-core/src/main/java/org/hibernate/query/sqm/ComparisonOperator.java

@@ -5,8 +5,12 @@
 package org.hibernate.query.sqm;
 
 /**
- * Defines the comparison operators.  We could also get away with
- * only 3 and use negation...
+ * Enumerates the binary comparison operators.
+ *
+ * @apiNote This is an SPI type allowing collaboration
+ * between {@code org.hibernate.dialect} and
+ * {@code org.hibernate.sqm}. It should never occur in
+ * APIs visible to the application program.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/query/sqm/DynamicInstantiationNature.java

@@ -10,6 +10,8 @@ import java.util.Map;
 /**
  * Represents the type of instantiation to be performed.
  *
+ * @see org.hibernate.query.sqm.tree.select.SqmDynamicInstantiationTarget#getNature
+ *
  * @author Steve Ebersole
  */
 public enum DynamicInstantiationNature {

hibernate-core/src/main/java/org/hibernate/query/sqm/SetOperator.java

@@ -7,41 +7,45 @@ package org.hibernate.query.sqm;
 /**
  * The SQL set operators.
  *
+ * @apiNote This is an SPI type. It should never occur
+ * in APIs visible to the application program.
+ *
  * @author Christian Beikov
  */
 public enum SetOperator {
 	/**
 	 * Union of sets that removes duplicate rows.
 	 */
-	UNION("union"),
+	UNION,
 	/**
 	 * Union of bags that retains all elements.
 	 */
-	UNION_ALL("union all"),
+	UNION_ALL,
 	/**
 	 * Intersection of sets that removes duplicate rows.
 	 */
-	INTERSECT("intersect"),
+	INTERSECT,
 	/**
 	 * Intersection of bags that retains duplicate matches.
 	 */
-	INTERSECT_ALL("intersect all"),
+	INTERSECT_ALL,
 	/**
 	 * Exclusion of set elements of the set on the right-hand side.
 	 */
-	EXCEPT("except"),
+	EXCEPT,
 	/**
 	 * Exclusion of bag elements of the bag on the right-hand side that retains duplicates.
 	 */
-	EXCEPT_ALL("except all");
-
-	private final String sqlString;
-
-	private SetOperator(String sqlString) {
-		this.sqlString = sqlString;
-	}
+	EXCEPT_ALL;
 
 	public String sqlString() {
-		return sqlString;
+		return switch (this) {
+			case UNION -> "union";
+			case UNION_ALL -> "union all";
+			case INTERSECT -> "intersect";
+			case INTERSECT_ALL -> "intersect all";
+			case EXCEPT -> "except";
+			case EXCEPT_ALL -> "except all";
+		};
 	}
 }

hibernate-core/src/main/java/org/hibernate/query/sqm/SqmQuerySource.java

@@ -5,14 +5,25 @@
 package org.hibernate.query.sqm;
 
 /**
- * Informational - used to identify the source of an SQM statement.
+ * Identifies the source of an SQM statement.
  *
  * @see org.hibernate.query.sqm.tree.SqmStatement#getQuerySource
  *
  * @author Steve Ebersole
  */
 public enum SqmQuerySource {
+	/**
+	 * The SQM tree represents a query written in HQL or JPQL.
+	 */
 	HQL,
+	/**
+	 * The SQM tree was built via the
+	 * {@linkplain org.hibernate.query.criteria.HibernateCriteriaBuilder
+	 * criteria query API}.
+	 */
 	CRITERIA,
+	/**
+	 * The SQM tree came from somewhere else.
+	 */
 	OTHER
 }

hibernate-core/src/main/java/org/hibernate/query/sqm/TrimSpec.java

@@ -5,11 +5,17 @@
 package org.hibernate.query.sqm;
 
 import jakarta.persistence.criteria.CriteriaBuilder;
-import org.hibernate.AssertionFailure;
 
 import java.util.Locale;
 
 /**
+ * Variations of the {@code trim()} function.
+ *
+ * @apiNote This is an SPI type allowing collaboration
+ * between {@code org.hibernate.dialect} and
+ * {@code org.hibernate.sqm}. It should never occur in
+ * APIs visible to the application program.
+ *
  * @author Steve Ebersole
  */
 public enum TrimSpec {
@@ -21,17 +27,12 @@ public enum TrimSpec {
 		if ( jpaTs == null ) {
 			return null;
 		}
-
-		switch ( jpaTs ) {
-			case BOTH:
-				return BOTH;
-			case LEADING:
-				return LEADING;
-			case TRAILING:
-				return TRAILING;
-			default:
-				throw new AssertionFailure( "Unrecognized JPA TrimSpec" );
-
+		else {
+			return switch ( jpaTs ) {
+				case BOTH -> BOTH;
+				case LEADING -> LEADING;
+				case TRAILING -> TRAILING;
+			};
 		}
 	}
 

hibernate-core/src/main/java/org/hibernate/query/sqm/UnaryArithmeticOperator.java

@@ -5,19 +5,23 @@
 package org.hibernate.query.sqm;
 
 /**
+ * Enumerates the unary prefix operators.
+ *
+ * @apiNote This is an SPI type allowing collaboration
+ * between {@code org.hibernate.dialect} and
+ * {@code org.hibernate.sqm}. It should never occur in
+ * APIs visible to the application program.
+ *
  * @author Steve Ebersole
  */
 public enum UnaryArithmeticOperator {
-	UNARY_PLUS( '+' ),
-	UNARY_MINUS( '-' );
-
-	private final char operatorChar;
-
-	UnaryArithmeticOperator(char operatorChar) {
-		this.operatorChar = operatorChar;
-	}
+	UNARY_PLUS,
+	UNARY_MINUS;
 
 	public char getOperatorChar() {
-		return operatorChar;
+		return switch ( this ) {
+			case UNARY_PLUS -> '+';
+			case UNARY_MINUS -> '-';
+		};
 	}
 }