more jdoc improvements to annotations

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

@@ -16,6 +16,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 /**
  * Specifies an expression written in native SQL that is used to read the value of
  * an attribute instead of storing the value in a {@link jakarta.persistence.Column}.
+ * <p>
  * A {@code Formula} mapping defines a "derived" attribute, whose state is determined
  * from other columns and functions when an entity is read from the database.
  * <p>
@@ -25,6 +26,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * &#64;Formula("sub_total + (sub_total * tax)")
  * long getTotalCost() { ... }
  * </pre>
+ * <p>
  * It may even call SQL functions:
  * <pre>
  * // call native SQL functions

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

@@ -16,19 +16,32 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 /**
  * 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}.
+ * The order is applied by the database when the collection is fetched,
+ * but is not maintained by operations that mutate the collection in
+ * memory.
+ * <p>
+ * 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}. If the collection is a bag or
+ * {@link java.util.List}, the order is maintained by the underlying
+ * {@link java.util.ArrayList}.
+ * <p>
+ * There are several other ways to order or sort a collection:
  * <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.
+ * <li>Use the JPA-defined {@link jakarta.persistence.OrderBy} annotation
+ *     to order using an expression written in HQL/JPQL. Since HQL is more
+ *     portable between databases, this is the preferred alternative most
+ *     of the time.
+ * <li>Use {@link SortComparator} to sort the collection in memory using
+ *     a {@link java.util.Comparator}, or {@link SortNatural} to sort the
+ *     collection in memory according to its {@linkplain 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}.
+ * It's illegal to use {@code OrderBy} together with the JPA-defined
+ * {@link jakarta.persistence.OrderBy} for the same collection.
  *
  * @see jakarta.persistence.OrderBy
  * @see SortComparator

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

@@ -38,6 +38,16 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * List<Document> documents;
  * </pre>
  * <p>
+ * The {@link WhereJoinTable} annotation lets a restriction be applied to
+ * an {@linkplain jakarta.persistence.JoinTable association table}:
+ * <pre>
+ * &#64;ManyToMany
+ * &#64;JoinTable(name = "collaborations")
+ * &#64;Where(clause = "status &lt;&gt; 'DELETED'")
+ * &#64;WhereJoinTable(clause = "status = 'ACTIVE'")
+ * List&lt;Document&gt; documents;
+ * </pre>
+ * <p>
  * By default, {@code @Where} restrictions declared for an entity are not
  * applied when loading a collection of that entity type. This behavior is
  * controlled by:
@@ -46,6 +56,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <li>the configuration property
  *     {@value org.hibernate.cfg.AvailableSettings#USE_ENTITY_WHERE_CLAUSE_FOR_COLLECTIONS}.
  * </ol>
+ * <p>
  * Note that {@code @Where} restrictions are always applied and cannot be
  * disabled. Nor may they be parameterized. They're therefore <em>much</em>
  * less flexible than {@linkplain Filter filters}.

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

@@ -6,26 +6,34 @@
  */
 package org.hibernate.annotations;
 
-import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
 /**
  * Specifies a restriction written in native SQL to add to the generated SQL
  * when querying the {@linkplain jakarta.persistence.JoinTable join table}
  * of a collection.
  * <p>
- * For example, <code>&#64;Where("status &lt;&gt; 'DELETED'")</code> could be
- * used to hide associations which have been soft-deleted from an association
- * table.
+ * For example, <code>&#64;WhereJoinTable("status &lt;&gt; 'DELETED'")</code>
+ * could be used to hide associations which have been soft-deleted from an
+ * association table.
+ *
+ * @apiNote This separate annotation is useful because it's possible to filter
+ *          a many-to-many association <em>both</em> by a restriction on the
+ *          join table, and, <em>simultaneously</em>, by a restriction on the
+ *          associated entity table. The {@link Where @Where} annotation always
+ *          filters entity tables.
  *
  * @author Emmanuel Bernard
  *
  * @see Where
  */
-@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
-@Retention(RetentionPolicy.RUNTIME)
+@Target({METHOD, FIELD})
+@Retention(RUNTIME)
 public @interface WhereJoinTable {
 	/**
 	 * A predicate, written in native SQL.

hibernate-core/src/main/java/org/hibernate/annotations/package-info.java

@@ -299,7 +299,7 @@
  * <li>{@link org.hibernate.annotations.Formula} allows a field or property to map to an
  *     arbitrary SQL expression instead of a column,
  * <li>{@link org.hibernate.annotations.Check} specifies a check constraint condition,
- * <li>{@link org.hibernate.annotations.ColumnDefault} specifies default value, and
+ * <li>{@link org.hibernate.annotations.ColumnDefault} specifies a default value, and
  *     {@link org.hibernate.annotations.GeneratedColumn} specifies a generated value,
  * <li>{@link org.hibernate.annotations.Filter} and {@link org.hibernate.annotations.Where}
  *     each specify a restriction written in SQL,

hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java

@@ -1715,7 +1715,7 @@ public abstract class CollectionBinder {
 		final String whereClause = getWhereClause();
 		if ( hasAssociationTable ) {
 			// A many-to-many association has an association (join) table
-			// Collection#setManytoManyWhere is used to set the "where" clause that applies to
+			// Collection#setManytoManyWhere is used to set the "where" clause that applies
 			// to the many-to-many associated entity table (not the join table).
 			collection.setManyToManyWhere( whereClause );
 		}