javadoc improvements

Author: gavinking

hibernate-core/src/main/java/org/hibernate/Interceptor.java

@@ -39,11 +39,14 @@
  * Whichever approach is used, the interceptor must be serializable for the
  * {@code Session} to be serializable. This means that {@code SessionFactory}-scoped
  * interceptors should implement {@code readResolve()}.
- * <p>
- * This venerable callback interface, dating to the very earliest days of Hibernate,
- * competes with JPA entity listener callbacks: {@link jakarta.persistence.PostLoad},
- * {@link jakarta.persistence.PrePersist} {@link jakarta.persistence.PreUpdate}, and
- * {@link jakarta.persistence.PreRemove}.
+ *
+ * @apiNote This venerable callback interface, dating from the very earliest days of
+ *          Hibernate, competes with standard JPA entity listener callbacks:
+ *          {@link jakarta.persistence.PostLoad}, {@link jakarta.persistence.PrePersist},
+ *          {@link jakarta.persistence.PreUpdate}, and {@link jakarta.persistence.PreRemove}.
+ *          However, JPA callbacks do not provide the ability to access the previous
+ *          value of an updated property in a {@code @PreUpdate} callback, and do not
+ *          provide a well-defined way to intercept changes to collections.
  *
  * @see SessionBuilder#interceptor(Interceptor)
  * @see SharedSessionBuilder#interceptor()

hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java

@@ -77,8 +77,11 @@
  *     annotated classes}, or {@linkplain #addFile XML mapping documents}.
  * </ul>
  * <p>
- * Note that XML mappings may be expressed using the JPA {@code orm.xml}
- * format, or in Hibernate's legacy {@code .hbm.xml} format.
+ * Note that XML mappings may be expressed using either:
+ * <ul>
+ * <li>the JPA-standard {@code orm.xml} format, or
+ * <li>the legacy {@code .hbm.xml} format, which is considered deprecated.
+ * </ul>
  * <p>
  * Configuration properties are enumerated by {@link AvailableSettings}.
  * <p>