add example to @Comment

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

@@ -28,6 +28,21 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <p>
  * But when {@link #on} is explicitly specified, the comment applies to the mapped table
  * or column with the specified name.
+ * <p>
+ * For example:
+ * <pre>
+ * &#64;Entity
+ * &#64;Table(name = "book")
+ * &#64;SecondaryTable(name = "edition")
+ * &#64;Comment("The primary table for Book")
+ * &#64;Comment(on = "edition",
+ *          value = "The secondary table for Book")
+ * class Book { ... }
+ * </pre>
+ *
+ * @apiNote In principle, it's possible for a column of a secondary table to have the
+ *          same name as a column of the primary table, or as a column of some other
+ *          secondary table. Therefore, {@link #on} may be ambiguous.
  *
  * @author Yanming Zhou
  */

hibernate-core/src/main/java/org/hibernate/binder/AttributeBinder.java

@@ -18,7 +18,7 @@ import java.lang.annotation.Annotation;
  * <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
+ * semantics of some {@linkplain org.hibernate.annotations.AttributeBinderType
  * custom mapping annotation}.
  *
  * @see org.hibernate.annotations.AttributeBinderType

hibernate-core/src/main/java/org/hibernate/binder/TypeBinder.java

@@ -18,7 +18,7 @@ import java.lang.annotation.Annotation;
  * <p>
  * An implementation of this interface interacts directly with model objects
  * like {@link PersistentClass} and {@link Component} to implement the
- * semantics of some {@link org.hibernate.annotations.TypeBinderType
+ * semantics of some {@linkplain org.hibernate.annotations.TypeBinderType
  * custom mapping annotation}.
  *
  * @see org.hibernate.annotations.TypeBinderType