improve javadoc for @Order/@Sort annotations

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

@@ -5,6 +5,7 @@
  * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -13,23 +14,34 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Order a collection using SQL ordering (not HQL ordering).
- *
- * Different from {@link jakarta.persistence.OrderBy} in that this expects SQL fragment, JPA OrderBy expects a
- * valid JPQL order-by fragment.
- *
- * @author Emmanuel Bernard
- * @author Steve Ebersole
+ * Order a collection using an expression written in native SQL.
+ * <p>
+ * The order is applied by the database when the collection is fetched, but is not maintained
+ * by operations that mutate the collection in memory. If the collection is a {@link java.util.Set}
+ * or {@link java.util.Map}, the order is maintained using a {@link java.util.LinkedHashSet} or
+ * {@link java.util.LinkedHashMap}.
+ * <ul>
+ * <li>Use {@link jakarta.persistence.OrderBy} to order using an expression written in HQL.
+ * <li>Use {@link SortComparator} to sort the collection in memory using a {@link java.util.Comparator}.
+ * <li>Use {@link SortNatural} to sort the collection in its {@link java.util.Comparator natural order}.
+ * <li>Use {@link jakarta.persistence.OrderColumn} to maintain the order of a {@link java.util.List}
+ *     with a dedicated index column.
+ * </ul>
+ * <p>
+ * It is illegal to use both {@code OrderBy} and {@link jakarta.persistence.OrderBy}.
  *
  * @see jakarta.persistence.OrderBy
  * @see SortComparator
  * @see SortNatural
+ *
+ * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface OrderBy {
 	/**
-	 * SQL ordering clause.
+	 * The native SQL expression used to sort the collection elements.
 	 */
 	String clause();
 }

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

@@ -15,15 +15,21 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Specifies in-memory Set/Map sorting using a specified {@link Comparator} for sorting.
+ * Sort a {@link java.util.Set} or {@link java.util.Map} using the given {@link Comparator}.
+ * <p>
+ * Sorting is performed in memory, by Java's {@link java.util.TreeSet} or {@link java.util.TreeMap},
+ * and is maintained by any operation that mutates the collection.
+ * <ul>
+ * <li>Use {@link SortNatural} in its {@link java.util.Comparator natural order}.
+ * <li>Use {@link jakarta.persistence.OrderBy} to order using an expression written in HQL.
+ * <li>Use {@link OrderBy} to order using an expression written in native SQL.
+ * </ul>
+ * <p>
+ * It is illegal to use both {@code SortComparator} and {@link SortNatural}.
  *
- * NOTE : Sorting is different than ordering (see {@link OrderBy}) which is applied during the SQL SELECT.
- *
- * For sorting based on natural sort order, use {@link SortNatural} instead.  It is illegal to combine
- * {@link SortComparator} and {@link SortNatural}.
- *
- * @see OrderBy
  * @see SortComparator
+ * @see jakarta.persistence.OrderBy
+ * @see OrderBy
  *
  * @author Steve Ebersole
  */
@@ -31,7 +37,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface SortComparator {
 	/**
-	 * Specifies the comparator class to use.
+	 * A class which implements {@link Comparator Comparator&lt;E&gt;} where {@code E} is the element type.
 	 */
 	Class<? extends Comparator<?>> value();
 }

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

@@ -14,15 +14,21 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Specifies in-memory Set/Map sorting using natural sorting.
+ * Sort a {@link java.util.Set} or {@link java.util.Map} in its {@link Comparable natural order}
+ * <p>
+ * Sorting is performed in memory, by Java's {@link java.util.TreeSet} or {@link java.util.TreeMap},
+ * and is maintained by any operation that mutates the collection.
+ * <ul>
+ * <li>Use {@link SortComparator} to sort the collection in memory using a {@link java.util.Comparator}.
+ * <li>Use {@link jakarta.persistence.OrderBy} to order using an expression written in HQL.
+ * <li>Use {@link OrderBy} to order using an expression written in native SQL.
+ * </ul>
+ * <p>
+ * It is illegal to use both {@code SortNatural} and {@link SortComparator}.
  *
- * NOTE : Sorting is different than ordering (see {@link OrderBy}) which is applied during the SQL SELECT.
- *
- * For sorting based on a comparator, use {@link SortComparator} instead.  It is illegal to combine
- *{@link SortComparator} and SortNatural.
- *
- * @see OrderBy
  * @see SortComparator
+ * @see jakarta.persistence.OrderBy
+ * @see OrderBy
  *
  * @author Steve Ebersole
  */