javadoc for @polymorphism

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

@@ -13,15 +13,50 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Used to define the type of polymorphism Hibernate will apply to entity hierarchies.
+ * Allows <em>implicit polymorphism</em> to be disabled for
+ * an entity class hierarchy, by annotating the root entity
+ * {@code @Polymorphism(type=EXPLICIT)}.
+ * <p>
+ * Hibernate allows a query {@code from} clause to name a
+ * {@linkplain org.hibernate.mapping.MappedSuperclass
+ * mapped superclass}, or even an arbitrary Java type which
+ * is neither an entity class nor a mapped superclass. The
+ * query will return all entities which inherit the type.
+ * For example, the query
+ *     <pre>{@code from java.lang.Object}</pre>
+ * will return every entity mapped by Hibernate!
+ * <p>
+ * This can be thought of as allowing a sort of "poor man's"
+ * {@linkplain jakarta.persistence.InheritanceType#TABLE_PER_CLASS
+ * table per class} inheritance, though it comes with many
+ * limitations.
+ * <p>
+ * This annotation allows an entity class to refuse to
+ * participate in such a crazy query, so that it's never
+ * returned by any query that names one of its non-entity
+ * supertypes.
+ * <p>
+ * Note that this annotation may only be applied to the root
+ * entity in an entity inheritance hierarchy, and its effect
+ * is inherited by entity subclasses.
+ * <p>
+ * Note also that this has <em>no effect at all</em> on the
+ * usual polymorphism within a mapped entity class inheritance
+ * hierarchy, as defied by the JPA specification. "Implicit"
+ * polymorphism is about queries that span multiple such
+ * entity inheritance hierarchies.
+ * <p>
+ * This annotation is hardly ever useful.
  *
  * @author Steve Ebersole
  */
 @Target( TYPE )
 @Retention( RUNTIME )
 public @interface Polymorphism {
 	/**
-	 * Specifies the polymorphism type.
+	 * Determines whether implicit polymorphism is enabled
+	 * or disabled for the annotated entity class. It is
+	 * enabled by default.
 	 */
 	PolymorphismType type() default PolymorphismType.IMPLICIT;
 }

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

@@ -9,19 +9,23 @@
 import java.util.Locale;
 
 /**
- * Type of available polymorphism for a particular entity.
+ * Specifies whether implicit polymorphism is enabled or disabled.
  *
  * @see Polymorphism
  *
  * @author Emmanuel Bernard
  */
 public enum PolymorphismType {
 	/**
-	 * This entity is retrieved if any of its super entity are retrieved.  The default,
+	 * Implicit polymorphism is enabled, and queries against mapped
+	 * superclasses and other arbitrary Java supertypes of an entity
+	 * will return instances of the entity.
 	 */
 	IMPLICIT,
 	/**
-	 * This entity is retrieved only if explicitly asked.
+	 * Implicit polymorphism is disabled, and queries against mapped
+	 * superclasses and other arbitrary Java supertypes of an entity
+	 * will not return the entity.
 	 */
 	EXPLICIT;