From 117851e4a4ed7ff119c469882ae7b7ae2bae9e70 Mon Sep 17 00:00:00 2001
From: Gavin <gavin@hibernate.org>
Date: Mon, 2 Jan 2023 02:28:56 +0100
Subject: [PATCH] add example to @Comment

---
 .../java/org/hibernate/annotations/Comment.java   | 15 +++++++++++++++
 .../org/hibernate/binder/AttributeBinder.java     |  2 +-
 .../java/org/hibernate/binder/TypeBinder.java     |  2 +-
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Comment.java b/hibernate-core/src/main/java/org/hibernate/annotations/Comment.java
index 78a8523ba2..aabec0139a 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/Comment.java
+++ b/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
  */
diff --git a/hibernate-core/src/main/java/org/hibernate/binder/AttributeBinder.java b/hibernate-core/src/main/java/org/hibernate/binder/AttributeBinder.java
index c5537ca68d..4eb497455c 100644
--- a/hibernate-core/src/main/java/org/hibernate/binder/AttributeBinder.java
+++ b/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
diff --git a/hibernate-core/src/main/java/org/hibernate/binder/TypeBinder.java b/hibernate-core/src/main/java/org/hibernate/binder/TypeBinder.java
index fc0188a3da..d3d3b33fed 100644
--- a/hibernate-core/src/main/java/org/hibernate/binder/TypeBinder.java
+++ b/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