improve the javadoc for AttributeBinder+AttributedBinderType

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
  */

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);
 }