improvements to javadoc for StatelessSession, Session, and overview page

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

@@ -25,16 +25,19 @@
  * with a logical transaction.
  * <p>
  * The lifecycle of a {@code Session} is bounded by the beginning and end of the logical
- * transaction. (But a long logical transaction might span several database transactions.)
+ * transaction. But a long logical transaction might span several database transactions.
  * <p>
  * The primary purpose of the {@code Session} is to offer create, read, and delete
  * operations for instances of mapped entity classes. An instance may be in one of three
- * states with respect to a given session:
+ * states with respect to a given open session:
  * <ul>
- * <li><em>transient:</em> never persistent, not associated with any {@code Session},
- * <li><em>persistent:</em> associated with a unique {@code Session}, or
- * <li><em>detached:</em> previously persistent, not associated with any {@code Session}
+ * <li><em>transient:</em> never persistent, and not associated with the {@code Session},
+ * <li><em>persistent:</em> currently associated with the {@code Session}, or
+ * <li><em>detached:</em> previously persistent, but not currently associated with the
+ *     {@code Session}.
  * </ul>
+ * At any given time, an instance may be associated with at most one open session.
+ * <p>
  * Any instance returned by {@link #get(Class, Object)} or by a query is persistent.
  * <p>
  * A transient instance may be made persistent by calling {@link #persist(Object)}.

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

@@ -7,18 +7,37 @@
 package org.hibernate;
 
 /**
- * A command-oriented API for performing bulk operations against a database.
+ * A command-oriented API often used for performing bulk operations against
+ * the database. A stateless session has no persistence context, and always
+ * works directly with detached entity instances. When a method of this
+ * interface is called, any necessary interaction with the database happens
+ * immediately and synchronously.
  * <p>
- * A stateless session does not implement a first-level cache nor interact
- * with any second-level cache, nor does it implement transactional
- * write-behind or automatic dirty checking, nor do operations cascade to
- * associated instances. Collections are ignored by a stateless session.
- * Operations performed via a stateless session bypass Hibernate's event model
- * and interceptors.  Stateless sessions are vulnerable to data aliasing
- * effects, due to the lack of a first-level cache.
+ * Viewed in opposition to to {@link Session}, the {@code StatelessSession}
+ * is a whole competing programming model, one preferred by some developers
+ * for its simplicity and somewhat lower level of abstraction. But the two
+ * kinds of session are not enemies, and may comfortably coexist in a single
+ * program.
  * <p>
- * For certain kinds of transactions, a stateless session may perform slightly
- * faster than a stateful session.
+ * A stateless session comes some with designed-in limitations:
+ * <ul>
+ * <li>it does not have a first-level cache,
+ * <li>nor interact with any second-level cache,
+ * <li>nor does it implement transactional write-behind or automatic dirty
+ *     checking, and
+ * <li>nor do operations cascade to associated instances.
+ * </ul>
+ * Furthermore:
+ * <ul>
+ * <li>collections are completely ignored by a stateless session, and
+ * <li>operations performed via a stateless session bypass Hibernate's event
+ *     model, lifecycle callbacks, and interceptors.
+ * </ul>
+ * Stateless sessions are vulnerable to data aliasing effects, due to the
+ * lack of a first-level cache.
+ * <p>
+ * On the other hand, for certain kinds of transactions, a stateless session
+ * may perform slightly faster than a stateful session.
  *
  * @author Gavin King
  */

release/src/release/javadoc/overview.html

@@ -8,58 +8,71 @@
 
 <h2>Hibernate ORM Aggregated Javadoc</h2>
 
-Hibernate provides:<ul>
+Hibernate is a library for object/relation mapping (ORM). It provides:<ul>
     <li>
         a <em>native API</em> centered around {@link org.hibernate.SessionFactory} and
         {@link org.hibernate.Session},
     </li>
     <li>
-        an implementation of the <em>Java (or Jakarta) Persistence API</em> (JPA), and
+        an implementation of the <em>Java (or Jakarta) Persistence API</em> (JPA),
+        where the equivalent central interfaces are {@link jakarta.persistence.EntityManagerFactory}
+        and {@link jakarta.persistence.EntityManager}, and
     </li>
     <li>
-        a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined by JPA,
-        and which may be used with either API.
+        a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined
+        by JPA, and which may be used with either API.
     </li>
 </ul>
 
 <h3>Native API</h3>
 
-Along with {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications using
-the native API will often make use of the following interfaces:<ul>
+Along with {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications
+using the native API will often make use of the following interfaces:<ul>
     <li>{@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
     <li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</li>
+    <li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
     <li>{@link org.hibernate.Transaction} to control local transactions, and</li>
     <li>{@link org.hibernate.query.Query} to execute HQL queries.</li>
 </ul>
 
 <h3>JPA</h3>
 
 The JPA interfaces are defined by the JPA specification. For details see the latest
-<a href="https://jakarta.ee/specifications/persistence/">specification</a> along with
-{@link jakarta.persistence}.
+<a href="https://jakarta.ee/specifications/persistence/">specification</a> along with the
+<a href="https://jakarta.ee/specifications/persistence/2.2/apidocs/">API documentation</a>
+for the package {@link jakarta.persistence}.
 
 <p>Note that since Hibernate 5.2, the native API extends the JPA API rather than wrapping it
 (for example,<code>SessionFactory</code> extends <code>EntityManagerFactory</code>).</p>
 
 <h3>Mapping annotations</h3>
 
-See {@link org.hibernate.annotations}.
+The mapping annotations defined by the JPA specification provide a foundation for expressing
+object/relational mappings in Hibernate and other JPA implementations.
+
+The annotations in the package {@link org.hibernate.annotations} extend this foundation and
+accommodate more specialized requirements. These annotation are not tied to the native API,
+and may be used in conjunction with the JPA API.
+
+The full power of Hibernate can only be unlocked via judicious use of these extra annotations.
 
 <h3>Note about package categories</h3>
+
 Hibernate categorizes packages into a number of groups based on intended consumers:<ul>
     <li>
-        <strong>API</strong> - classes to which application code will generally bind directly. These
-        are generally classes which do not have "spi" nor "internal" in their package path and are
-        not under the "org.hibernate.testing" package
+        <strong>API</strong> - classes to which application code will generally bind directly.
+        These  are generally classes which do not have <code>spi</code> nor <code>internal</code>
+        in their package path and are not under the package <code>org.hibernate.testing</code>.
     </li>
     <li>
-        <strong>SPI</strong> - classes to which integrator developers will commonly bind directly in
-        order to develop extensions to Hibernate, or to alter its behavior in some way. These are
-        generally under packages with "spi" in the package path.
+        <strong>SPI</strong> - classes to which integrator developers will commonly bind directly
+        in order to develop extensions to Hibernate, or to alter its behavior in some way. These
+        are generally under packages with <code>spi</code> in the package path.
     </li>
     <li>
-        <strong>Testing Support</strong> - classes from the hibernate-testing artifact used in building
-        Hibernate test cases. These are classes under the "org.hibernate.testing" package
+        <strong>Testing Support</strong> - classes from the <code>hibernate-testing</code>
+        artifact used in building Hibernate test cases. These are classes under the package
+        <code>org.hibernate.testing</code>.
     </li>
 </ul>
 <p></p>