improve some more javadoc

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

@@ -9,33 +9,49 @@ package org.hibernate;
 /**
  * Represents an association fetching strategy.
  *
+ * @apiNote This enumeration was previously used to override
+ * the fetching strategy specified by mapping annotations when
+ * using the old criteria query API. Now it is only used by
+ * SPIs and internal APIs.
+ *
+ * @see org.hibernate.annotations.FetchMode
+ *
  * @author Gavin King
  */
 public enum FetchMode  {
+
 	/**
-	 * Default to the setting configured in the mapping file.
+	 * Use the default fetching strategy specified by the
+	 * {@linkplain org.hibernate.annotations.Fetch mapping
+	 * annotations}.
 	 */
 	DEFAULT,
 
 	/**
-	 * Fetch using an outer join. Equivalent to {@code fetch="join"}.
+	 * Fetch in the initial select, using an outer join.
+	 *
+	 * @see org.hibernate.annotations.FetchMode#JOIN
 	 */
 	JOIN,
+
 	/**
-	 * Fetch eagerly, using a separate select. Equivalent to
-	 * {@code fetch="select"}.
+	 * Fetch using a separate subsequent select.
+	 *
+	 * @see org.hibernate.annotations.FetchMode#SELECT
+	 * @see org.hibernate.annotations.FetchMode#SUBSELECT
 	 */
 	SELECT;
 
 	/**
-	 * Fetch lazily. Equivalent to {@code outer-join="false"}.
+	 * Fetch lazily, using a separate select.
 	 *
 	 * @deprecated use {@link #SELECT}
 	 */
 	@Deprecated
 	public static final FetchMode LAZY = SELECT;
+
 	/**
-	 * Fetch eagerly, using an outer join. Equivalent to {@code outer-join="true"}.
+	 * Fetch eagerly, using an outer join.
 	 *
 	 * @deprecated use {@link #JOIN}
 	 */

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

@@ -13,7 +13,11 @@ import jakarta.persistence.FlushModeType;
 /**
  * Represents a flushing strategy. The flush process synchronizes
  * database state with session state by detecting state changes
- * and executing SQL statements.
+ * and executing SQL statements. A value of this enumeration
+ * specifies <em>when</em> the flush process occurs.
+ * <p>
+ * For example, {@link #COMMIT} specifies that the session flushes
+ * automatically when the transaction is about to commit.
  *
  * @see Session#setHibernateFlushMode
  * @see org.hibernate.query.CommonQueryContract#setHibernateFlushMode

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

@@ -17,8 +17,8 @@ import org.hibernate.type.Type;
  * Allows user code to inspect and/or change entity property values before they are
  * written to the database, or after the are read from the database.
  * <p>
- * The {@code Session} may not be invoked from a callback (nor may a callback cause a
- * collection or proxy to be lazily initialized).
+ * The {@link Session} may not be invoked from a callback (nor may a callback cause
+ * a collection or proxy to be lazily initialized).
  * <p>
  * There might be a single instance of {@code Interceptor} for a {@link SessionFactory},
  * or a new instance might be created for each {@link Session}. Use:

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

@@ -9,9 +9,11 @@ package org.hibernate;
 import org.hibernate.type.BasicType;
 
 /**
- * Represents a replication strategy.
+ * Represents a replication strategy used by
+ * {@link Session#replicate(Object, ReplicationMode)}.
  *
  * @author Gavin King
+ *
  * @see Session#replicate(Object, ReplicationMode)
  */
 public enum ReplicationMode {

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

@@ -9,7 +9,8 @@ package org.hibernate;
 import java.sql.ResultSet;
 
 /**
- * Specifies the type of JDBC scrollable result set to use underneath a {@link ScrollableResults}.
+ * Specifies the type of JDBC scrollable {@linkplain ResultSet result set}
+ * to use underneath a {@link ScrollableResults}.
  *
  * @author Gavin King
  */
@@ -22,14 +23,16 @@ public enum ScrollMode {
 	FORWARD_ONLY( ResultSet.TYPE_FORWARD_ONLY ),
 
 	/**
-	 * Requests a scrollable result which is sensitive to changes in the underlying data.
+	 * Requests a scrollable result which is sensitive to changes
+	 * in the underlying data.
 	 *
 	 * @see ResultSet#TYPE_SCROLL_SENSITIVE
 	 */
 	SCROLL_SENSITIVE( ResultSet.TYPE_SCROLL_SENSITIVE ),
 
 	/**
-	 * Requests a scrollable result which is insensitive to changes in the underlying data.
+	 * Requests a scrollable result which is insensitive to changes
+	 * in the underlying data.
 	 *
 	 * Note that since the Hibernate session acts as a cache, you
 	 * might need to explicitly evict objects, if you need to see

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

@@ -11,11 +11,12 @@ import java.io.Closeable;
 import org.hibernate.query.Query;
 
 /**
- * A result iterator that allows moving around within the results
- * by arbitrary increments. The {@code Query} / {@code ScrollableResults}
- * pattern is very similar to the JDBC {@code PreparedStatement}/
- * {@code ResultSet} pattern and the semantics of methods of this interface
- * are similar to the similarly named methods on {@code ResultSet}.
+ * A result iterator that allows moving around within the results by
+ * arbitrary increments. The {@link Query} / {@link ScrollableResults}
+ * pattern is very similar to the JDBC {@link java.sql.PreparedStatement}/
+ * {@link java.sql.ResultSet} pattern and so the semantics of methods
+ * of this interface are similar to the similarly-named methods of
+ * {@code ResultSet}.
  * <p>
  * Contrary to JDBC, columns of results are numbered from zero.
  *
@@ -51,9 +52,11 @@ public interface ScrollableResults<R> extends AutoCloseable, Closeable {
 	boolean previous();
 
 	/**
-	 * Scroll the specified number of positions from the current position.
+	 * Scroll the specified number of positions from the current
+	 * position.
 	 *
-	 * @param positions a positive (forward) or negative (backward) number of rows
+	 * @param positions a positive (forward) or negative (backward)
+	 *                  number of rows
 	 *
 	 * @return {@code true} if there is a result at the new location
 	 */
@@ -81,7 +84,9 @@ public interface ScrollableResults<R> extends AutoCloseable, Closeable {
 	boolean first();
 
 	/**
-	 * Go to a location just before first result,  This is the location of the cursor on a newly returned
+	 * Go to a location just before first result.
+	 * <p>
+	 * This is the location of the cursor on a newly returned
 	 * scrollable result.
 	 */
 	void beforeFirst();
@@ -94,7 +99,8 @@ public interface ScrollableResults<R> extends AutoCloseable, Closeable {
 	/**
 	 * Is this the first result?
 	 *
-	 * @return {@code true} if this is the first row of results, otherwise {@code false}
+	 * @return {@code true} if this is the first row of results,
+	 *         otherwise {@code false}
 	 */
 	boolean isFirst();
 
@@ -106,18 +112,25 @@ public interface ScrollableResults<R> extends AutoCloseable, Closeable {
 	boolean isLast();
 
 	/**
-	 * Get the current position in the results. The first position is number 0 (unlike JDBC).
+	 * Get the current position in the results.
+	 * <p>
+	 * The first position is number 0 (unlike JDBC).
 	 *
-	 * @return The current position number, numbered from 0; -1 indicates that there is no current row
+	 * @return The current position number, numbered from 0;
+	 *         -1 indicates that there is no current row
 	 */
 	int getRowNumber();
 
 	/**
-	 * Set the current position in the result set.  Can be numbered from the first position (positive number) or
-	 * the last row (negative number).
+	 * Set the current position in the result set.
+	 * <p>
+	 * Can be numbered from the first result (positive number)
+	 * or backward from the last result (negative number).
 	 *
-	 * @param rowNumber the row number.  A positive number indicates a value numbered from the first row; a
-	 * negative number indicates a value numbered from the last row.
+	 * @param rowNumber the row number. A positive number indicates
+	 *                  a value numbered from the first row; a
+	 *                  negative number indicates a value numbered
+	 *                  from the last row.
 	 *
 	 * @return true if there is a row at that row number
 	 */

hibernate-core/src/main/java/org/hibernate/cfg/annotations/MapBinder.java

@@ -45,7 +45,6 @@ import org.hibernate.mapping.OneToMany;
 import org.hibernate.mapping.PersistentClass;
 import org.hibernate.mapping.Property;
 import org.hibernate.mapping.Selectable;
-import org.hibernate.mapping.SemanticsResolver;
 import org.hibernate.mapping.SimpleValue;
 import org.hibernate.mapping.Table;
 import org.hibernate.mapping.Value;