From 75fc936b95e6a97e2df5ed58afe8c653b3ba8b32 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Thu, 9 Dec 2021 11:56:17 +0100
Subject: [PATCH] improve the javadoc for AttributeBinder+AttributedBinderType

---
 .../annotations/AttributeBinderType.java        |  4 ++++
 .../org/hibernate/tuple/AttributeBinder.java    | 17 +++++++++++++++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/AttributeBinderType.java b/hibernate-core/src/main/java/org/hibernate/annotations/AttributeBinderType.java
index a1779801a4..ff1928f3b5 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/AttributeBinderType.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/AttributeBinderType.java
@@ -18,6 +18,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 /**
  * Associates a user-defined annotation with an {@link AttributeBinder},
  * allowing the annotation to drive some custom model binding.
+ * <p>
+ * The user-defined annotation may be used to annotate fields and
+ * properties of entity and embeddable classes. The {@code AttributeBinder}
+ * will be called when the annotation is discovered by Hibernate.
  *
  * @author Gavin King
  */
diff --git a/hibernate-core/src/main/java/org/hibernate/tuple/AttributeBinder.java b/hibernate-core/src/main/java/org/hibernate/tuple/AttributeBinder.java
index ee2b13f746..827a8da849 100644
--- a/hibernate-core/src/main/java/org/hibernate/tuple/AttributeBinder.java
+++ b/hibernate-core/src/main/java/org/hibernate/tuple/AttributeBinder.java
@@ -15,6 +15,11 @@ import java.lang.annotation.Annotation;
 
 /**
  * Allows a user-written annotation to drive some customized model binding.
+ * <p>
+ * An implementation of this interface interacts directly with model objects
+ * like {@link PersistentClass} and {@link Property} to implement the
+ * semantics of some {@link org.hibernate.annotations.AttributeBinderType
+ * custom mapping annotation}.
  *
  * @see org.hibernate.annotations.AttributeBinderType
  *
@@ -23,8 +28,16 @@ import java.lang.annotation.Annotation;
 @Incubating
 public interface AttributeBinder<A extends Annotation> {
 	/**
-	 * Perform some custom configuration of the model relating to the given {@link Property}
-	 * of the given {@link PersistentClass}.
+	 * Perform some custom configuration of the model relating to the given annotated
+	 * {@link Property} of the given {@link PersistentClass entity class} or
+	 * {@link org.hibernate.mapping.Component embeddable class}.
+	 *
+	 * @param annotation an annotation of the property that is declared as an
+	 *                   {@link org.hibernate.annotations.AttributeBinderType}
+	 * @param persistentClass the entity class acting as the ultimate container of the
+	 *                        property (differs from {@link Property#getPersistentClass()}
+	 *                        in the case of a property of an embeddable class)
+	 * @param property a {@link Property} object representing the annotated property
 	 */
 	void bind(A annotation, MetadataBuildingContext buildingContext, PersistentClass persistentClass, Property property);
 }