improve javadoc for @JoinFormula-related stuff

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

@@ -16,8 +16,14 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Allows joins based on column or a formula.  One of {@link #formula()} or {@link #column()} should be
- * specified, but not both.
+ * Specifies one element of a {@linkplain JoinColumnsOrFormulas composite join condition}
+ * involving both {@linkplain JoinFormula formulas} and {@linkplain JoinColumn columns}.
+ * One of {@link #formula()} or {@link #column()} must be specified, but not both. If a
+ * composite join condition involves only columns, this annotation is unnecessary.
+ *
+ * @see JoinColumnsOrFormulas
+ * @see JoinFormula
+ * @see JoinColumn
  *
  * @author Sharath Reddy
  */
@@ -26,12 +32,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Repeatable(JoinColumnsOrFormulas.class)
 public @interface JoinColumnOrFormula {
 	/**
-	 * The formula to use in joining.
+	 * The formula to use in the join condition.
 	 */
 	JoinFormula formula() default @JoinFormula(value="", referencedColumnName="");
 
 	/**
-	 * The column to use in joining.
+	 * The column to use in the join condition.
 	 */
 	JoinColumn column() default @JoinColumn();
 }

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

@@ -6,6 +6,8 @@
  */
 
 package org.hibernate.annotations;
+import jakarta.persistence.JoinColumn;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -14,15 +16,20 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Collection of {@code @JoinColumnOrFormula} definitions.
+ * Specifies a composite join condition involving one or more {@linkplain JoinFormula formulas}
+ * and, optionally, one or more {@linkplain JoinColumn columns}. If a join condition has just
+ * one column or formula, or involves only columns, this annotation is unnecessary.
  *
  * @author Sharath Reddy
+ *
+ * @see JoinColumnOrFormula
+ * @see jakarta.persistence.JoinColumns
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface JoinColumnsOrFormulas {
 	/**
-	 * The aggregated values.
+	 * A list of columns and formulas to use in the join condition.
 	 */
 	JoinColumnOrFormula[] value();
 }

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

@@ -14,8 +14,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * To be used as a replacement for {@code @JoinColumn} in most places.  The formula has to be a valid
- * SQL fragment
+ * Specifies a join condition based on an arbitrary native SQL formula
+ * instead of a {@linkplain jakarta.persistence.JoinColumn column name}.
  *
  * @author Sharath Reddy
  */
@@ -23,7 +23,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface JoinFormula {
 	/**
-	 * The formula.
+	 * The formula, in native SQL.
 	 */
 	String value();