add some javadoc

Author: gavinking

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

@@ -183,13 +183,13 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void setFlushMode(FlushModeType flushMode);
 
 	/**
-	 * Set the current {@link FlushMode flush mode} for this session.
+	 * Set the current {@linkplain FlushMode flush mode} for this session.
 	 * <p>
 	 * <em>Flushing</em> is the process of synchronizing the underlying persistent
 	 * store with persistable state held in memory. The current flush mode determines
 	 * when the session is automatically flushed.
 	 * <p>
-	 * The {@link FlushMode#AUTO default flush mode} is sometimes unnecessarily
+	 * The {@linkplain FlushMode#AUTO default flush mode} is sometimes unnecessarily
 	 * aggressive. For a logically "read only" session, it's reasonable to set the
 	 * session's flush mode to {@link FlushMode#MANUAL} at the start of the session
 	 * in order to avoid some unnecessary work.
@@ -201,22 +201,22 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void setHibernateFlushMode(FlushMode flushMode);
 
 	/**
-	 * Get the current {@link FlushModeType JPA flush mode} for this session.
+	 * Get the current {@linkplain FlushModeType JPA flush mode} for this session.
 	 *
 	 * @return the {@link FlushModeType} currently in effect
 	 */
 	@Override
 	FlushModeType getFlushMode();
 
 	/**
-	 * Get the current {@link FlushMode flush mode} for this session.
+	 * Get the current {@linkplain FlushMode flush mode} for this session.
 	 *
 	 * @return the {@link FlushMode} currently in effect
 	 */
 	FlushMode getHibernateFlushMode();
 
 	/**
-	 * Set the current {@link CacheMode cache mode} for this session.
+	 * Set the current {@linkplain CacheMode cache mode} for this session.
 	 * <p>
 	 * The cache mode determines the manner in which this session can interact with
 	 * the second level cache.
@@ -226,7 +226,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void setCacheMode(CacheMode cacheMode);
 
 	/**
-	 * Get the current {@link CacheMode cache mode} for this session.
+	 * Get the current {@linkplain CacheMode cache mode} for this session.
 	 *
 	 * @return the current cache mode
 	 */

hibernate-core/src/main/java/org/hibernate/query/CommonQueryContract.java

@@ -24,9 +24,30 @@
  * forms of querying: HQL/JPQL queries, native SQL queries,
  * {@linkplain jakarta.persistence.criteria.CriteriaBuilder criteria queries}, and
  * {@linkplain org.hibernate.procedure.ProcedureCall stored procedure calls}.
+ * <p>
+ * Queries may have <em>parameters</em>, either ordinal or named, and the various
+ * {@code setParameter()} operations of this interface allow an argument to be
+ * bound to a parameter. It's not usually necessary to explicitly specify the type
+ * of an argument, but in rare cases where this is needed, {@link TypedParameterValue}
+ * may be used.
+ * <p>
+ * The operation {@link #setFlushMode(FlushModeType)} allows a temporary flush
+ * mode to be specified, which is in effect only during the execution of this query.
+ * Setting the {@linkplain FlushMode flush mode} at the query level does not affect
+ * the flush mode of other operations performed via the parent {@linkplain Session
+ * session}. This operation is usually used as follows:
+ * <p>
+ * <pre>query.setFlushMode(COMMIT).getResultList()</pre>
+ * <p>
+ * The call to {@code setFlushMode(COMMIT)} disables the usual automatic flush
+ * operation that occurs before query execution.
  *
  * @author Steve Ebersole
  * @author Gavin King
+ *
+ * @see jakarta.persistence.Query
+ * @see SelectionQuery
+ * @see MutationQuery
  */
 public interface CommonQueryContract {
 

hibernate-core/src/main/java/org/hibernate/query/TypedParameterValue.java

@@ -10,10 +10,35 @@
 import org.hibernate.type.BasicTypeReference;
 
 /**
- * Can be used to bind query parameter values.  Allows providing additional details about the
- * parameter value/binding.
+ * Represents a typed argument to a query parameter.
+ * <p>
+ * Usually, the {@linkplain org.hibernate.type.Type Hibernate type} of
+ * an argument to a query parameter may be inferred, and so it's rarely
+ * necessary to explicitly pass a type when binding the argument.
+ * Occasionally, and especially when the argument is null, the type
+ * cannot be inferred and must be explicitly specified. In such cases,
+ * an instance of {@code TypedParameterValue} may be passed to
+ * {@link jakarta.persistence.Query#setParameter setParameter()}.
+ * <p>
+ * For example:
+ * <pre>
+ * query.setParameter("stringNamedParam",
+ *         new TypedParameterValue(StandardBasicTypes.STRING, null))
+ * </pre>
+ * <p>
+ * Here, a "null string" argument was bound to the named parameter
+ * {@code :stringNamedParam}.
  *
  * @author Steve Ebersole
+ *
+ * @since 6
+ *
+ * @see jakarta.persistence.Query#setParameter(int, Object)
+ * @see jakarta.persistence.Query#setParameter(String, Object)
+ * @see CommonQueryContract#setParameter(int, Object)
+ * @see CommonQueryContract#setParameter(String, Object)
+ *
+ * @see org.hibernate.type.StandardBasicTypes
  */
 public final class TypedParameterValue<J> {