HHH-18060 - HbmXmlTransformer

apiNOte on @PropertyRef

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

@@ -13,6 +13,9 @@ import java.lang.annotation.Retention;
 
 import org.hibernate.Incubating;
 
+import jakarta.persistence.ManyToMany;
+import jakarta.persistence.OneToMany;
+
 /**
  * Allows to specify the target of a foreign-key using a "target attribute" as opposed to
  * join column(s).  E.g.
@@ -55,6 +58,9 @@ import org.hibernate.Incubating;
  *     }
  * </pre>
  *
+ * @apiNote As Hibernate allows {@linkplain OneToMany#mappedBy()} and {@linkplain ManyToMany#mappedBy()} to refer
+ * to basic and embedded attributes already, this annotation is mainly useful for mapping to-one associations.
+ *
  * @author Steve Ebersole
  */
 @Target({ElementType.FIELD,ElementType.METHOD,ElementType.ANNOTATION_TYPE})