clarify the usage of @XxxxTable annotations (#587)

see #586

Co-authored-by: Lukas Jungmann <[email protected]>

api/src/main/java/jakarta/persistence/CollectionTable.java

@@ -92,6 +92,9 @@
  * }
  * }
  *
+ * <p>This annotation may not be applied to a persistent field or property
+ * not annotated {@link ElementCollection}.
+ *
  * @see ElementCollection
  * @see AttributeOverride
  * @see AssociationOverride

api/src/main/java/jakarta/persistence/JoinTable.java

@@ -50,7 +50,11 @@
  *     joinColumns = @JoinColumn(name = "CUST_ID", referencedColumnName = "ID"),
  *     inverseJoinColumns = @JoinColumn(name = "PHONE_ID", referencedColumnName = "ID"))
  * }
- * 
+ *
+ * <p>This annotation may not be applied to a persistent field or property
+ * not annotated {@link ManyToOne}, {@link OneToOne}, {@link ManyToMany},
+ * or {@link OneToMany}.
+ *
  * @see JoinColumn
  * @see JoinColumns
  *

api/src/main/java/jakarta/persistence/SecondaryTable.java

@@ -56,6 +56,9 @@
  * public class Customer { ... }
  * }
  *
+ * <p>This annotation may not be applied to a class annotated
+ * {@link MappedSuperclass} or {@link Embeddable}.
+ *
  * @since 1.0
  */
 @Repeatable(SecondaryTables.class)

api/src/main/java/jakarta/persistence/Table.java

@@ -37,6 +37,9 @@
  * public class Customer { ... }
  * }
  *
+ * <p>This annotation may not be applied to a class annotated
+ * {@link MappedSuperclass} or {@link Embeddable}.
+ *
  * @since 1.0
  */
 @Target(TYPE) 

spec/src/main/asciidoc/ch02-entities.adoc

@@ -2163,14 +2163,14 @@ A class designated as a mapped superclass has
 no separate table defined for it. Its mapping information is applied to
 the entities that inherit from it.
 
-A class designated as a mapped superclass can
-be mapped in the same way as an entity except that the mappings will
-apply only to its subclasses since no table exists for the mapped
-superclass itself. When applied to the subclasses, the inherited
-mappings will apply in the context of the subclass tables. Mapping
-information can be overridden in such subclasses by using the
-`AttributeOverride` and `AssociationOverride` annotations or
-corresponding XML elements.
+The persistent attributes of a mapped superclass may be mapped in the same
+way as the attributes of an entity class. Such mappings apply only to the
+entity subclasses of the mapped superclass, since no table exists for the
+mapped superclass itself. When applied to a subclass, the inherited mappings
+are interpreted in the context of the tables mapped by subclass. Mapping
+information inherited from a mapped superclass can be overridden in such
+subclasses using the `AttributeOverride` and `AssociationOverride`
+annotations or corresponding XML elements.
 
 All other entity mapping defaults apply
 equally to a class designated as a mapped superclass.

spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc

@@ -717,6 +717,9 @@ If the `CollectionTable` annotation is
 missing, the default values of the `CollectionTable` annotation elements
 apply.
 
+This annotation may not be applied to a persistent field or property not
+annotated `@ElementCollection`.
+
 <<a14269>> lists the annotation elements that
 may be specified for the `CollectionTable` annotation and their default
 values.
@@ -2579,6 +2582,9 @@ relationship with an embeddable class on the owning side of the
 relationship, the containing entity rather than the embeddable class is
 considered the owner of the relationship.
 
+This annotation may not be applied to a persistent field or property
+not annotated `@ManyToOne`, `@OneToOne`, `@ManyToMany`, or `@OneToMany`.
+
 [source,java]
 ----
 @Target({METHOD, FIELD})
@@ -4774,6 +4780,9 @@ effect. If both this element and the `foreignKey` element of any of the
 `foreignKey` annotation element is specified in either location, the
 persistence provider's default foreign key strategy will apply.
 
+This annotation may not be applied to a class annotated `@MappedSuperclass`
+or `@Embeddable`.
+
 [source,java]
 ----
 @Target({TYPE})
@@ -5080,6 +5089,9 @@ If no `Table` annotation is specified for an
 entity class, the default values defined in
 <<a16232>> apply.
 
+This annotation may not be applied to a class annotated `@MappedSuperclass`
+or `@Embeddable`.
+
 [source,java]
 ----
 @Target({TYPE})