various jdoc format fixes + improve a package-info

- add some periods
- fix up all the code snippets I messed up
- add some <p>s after lists and code blocks
- improve section of package-info which was hard to understand
- fix jdoc for LobHelper
- fix code example in @ValueGenerationType

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

@@ -18,6 +18,7 @@
  *     a given {@link SessionFactory}. It stores the state of an entity instance
  *     in a destructured format, as a tuple of persistent attribute values.
  * </ul>
+ * <p>
  * By nature, a second-level cache tends to undermine the ACID properties of
  * transaction processing in a relational database. A second-level cache is often
  * by far the easiest way to improve the performance of a system, but only at the
@@ -76,6 +77,7 @@
  * <li>{@linkplain org.hibernate.annotations.CacheConcurrencyStrategy#TRANSACTIONAL
  *     transactional access} when concurrent updates are frequent.
  * </ul>
+ * <p>
  * It's important to always explicitly specify an appropriate policy, taking into
  * account the expected patterns of data access, most importantly, the frequency
  * of updates.

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

@@ -63,6 +63,7 @@ public enum CacheMode {
 	 * <li>enabled for a cache where writes are much more expensive than
 	 *     reads, which is usually the case for a distributed cache.
 	 * </ul>
+	 * <p>
 	 * It's not usually necessary to specify this setting explicitly because,
 	 * by default, it's set to a sensible value by the second-level cache
 	 * implementation.

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

@@ -29,6 +29,7 @@
  *         specify that there is a dedicated instance of the interceptor for each
  *         session.
  * </ul>
+ * <p>
  * 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()}.
@@ -347,6 +348,7 @@ default void postFlush(Iterator<Object> entities) throws CallbackException {}
 	 * <li>{@code null} - Hibernate uses the {@code unsaved-value} mapping and other heuristics to 
 	 * determine if the object is unsaved
 	 * </ul>
+	 *
 	 * @param entity a transient or detached entity
 	 * @return Boolean or {@code null} to choose default behaviour
 	 */

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

@@ -13,7 +13,7 @@
 import java.sql.NClob;
 
 /**
- * A {@link Session session's} helper for creating LOB data.
+ * A factory for instances of {@link Blob} and {@link Clob} used for writing LOB data.
  *
  * @author Steve Ebersole
  */

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

@@ -34,6 +34,7 @@
  * <li>the {@link #getLockScope() lock scope}, that is, whether the
  *     lock extends to rows of owned collections.
  * </ul>
+ * <p>
  * Timeout and lock scope are ignored if the specified {@code LockMode}
  * represents a flavor of {@linkplain LockMode#OPTIMISTIC optimistic}
  * locking.

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

@@ -17,6 +17,7 @@
  *     is null, or
  * <li>an association references an unsaved transient instance.
  * </ul>
+ * 
  * @author Gavin King
  */
 public class PropertyValueException extends HibernateException {

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

@@ -39,6 +39,7 @@
  * <li><em>detached:</em> previously persistent, but not currently associated with the
  *     {@code Session}.
  * </ul>
+ * <p>
  * 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.
@@ -63,11 +64,11 @@
  * detached instance to the persistent state are now deprecated, and clients should now
  * migrate to the use of {@code merge()}.
  * <p>
- * From {@link FlushMode time to time}, the session performs a {@linkplain #flush() flushing}
- * operation, and synchronizes state held in memory with persistent state held in the
- * database by executing SQL {@code insert}, {@code update}, and {@code delete} statements.
- * Note that SQL statements are often not executed synchronously by the methods of the
- * {@code Session} interface. If synchronous execution of SQL is desired, the
+ * From {@linkplain FlushMode time to time}, a {@linkplain #flush() flush operation} is
+ * triggered, and the session synchronizes state held in memory with persistent state
+ * held in the database by executing SQL {@code insert}, {@code update}, and {@code delete}
+ * statements. Note that SQL statements are often not executed synchronously by the methods
+ * of the {@code Session} interface. If synchronous execution of SQL is desired, the
  * {@link StatelessSession} allows this.
  * <p>
  * A persistence context holds hard references to all its entities and prevents them
@@ -706,6 +707,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 * <li>perform a version check with {@link LockMode#READ}, or
 	 * <li>upgrade to a pessimistic lock with {@link LockMode#PESSIMISTIC_WRITE}).
 	 * </ul>
+	 * <p>
 	 * This operation cascades to associated instances if the association is
 	 * mapped with {@link org.hibernate.annotations.CascadeType#LOCK}.
 	 *
@@ -735,6 +737,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 * <li>perform a version check with {@link LockMode#READ}, or
 	 * <li>upgrade to a pessimistic lock with {@link LockMode#PESSIMISTIC_WRITE}).
 	 * </ul>
+	 * <p>
 	 * This operation cascades to associated instances if the association is
 	 * mapped with {@link org.hibernate.annotations.CascadeType#LOCK}.
 	 *
@@ -756,6 +759,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 * <li>the {@linkplain LockRequest#setLockScope(PessimisticLockScope) scope}
 	 *     that is, whether the lock extends to rows of owned collections.
 	 * </ul>
+	 * <p>
 	 * Timeout and scope are ignored if the specified {@code LockMode} represents
 	 * a flavor of {@linkplain LockMode#OPTIMISTIC optimistic} locking.
 	 * <p>
@@ -782,6 +786,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *     SQL statement
 	 * <li>after inserting a {@link java.sql.Blob} or {@link java.sql.Clob}
 	 * </ul>
+	 * <p>
 	 * This operation cascades to associated instances if the association is mapped
 	 * with {@link jakarta.persistence.CascadeType#REFRESH}.
 	 * <p>
@@ -803,6 +808,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *     SQL statement
 	 * <li>after inserting a {@link java.sql.Blob} or {@link java.sql.Clob}
 	 * </ul>
+	 * <p>
 	 * This operation cascades to associated instances if the association is mapped
 	 * with {@link jakarta.persistence.CascadeType#REFRESH}.
 	 *
@@ -1264,9 +1270,10 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void disableFetchProfile(String name) throws UnknownProfileException;
 
 	/**
-	 * Retrieve this session's helper/delegate for creating LOB instances.
+	 * Obtain a {@linkplain LobHelper factory} for instances of {@link java.sql.Blob}
+	 * and {@link java.sql.Clob}.
 	 *
-	 * @return this session's {@link LobHelper LOB helper}
+	 * @return an instance of {@link LobHelper}
 	 */
 	LobHelper getLobHelper();
 

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

@@ -31,7 +31,7 @@
  * affects the runtime behavior of Hibernate, and instances of services that
  * Hibernate needs to perform its duties.
  * <p>
- * Crucially, this is where a program comes to obtain {@link Session sessions}.
+ * Crucially, this is where a program comes to obtain {@linkplain Session sessions}.
  * Typically, a program has a single {@link SessionFactory} instance, and must
  * obtain a new {@link Session} instance from the factory each time it services
  * a client request.
@@ -51,7 +51,7 @@
  * There are some interesting exceptions to this principle:
  * <ul>
  * <li>Each {@code SessionFactory} has its own isolated second-level cache,
- *     shared between the sessions it creates, and it {@link #getCache()
+ *     shared between the sessions it creates, and it {@linkplain #getCache()
  *     exposes the cache} to clients as a stateful object with entries that
  *     may be queried and managed directly.
  * <li>Similarly, the factory {@linkplain #getStatistics() exposes} a
@@ -67,6 +67,7 @@
  *     motivation to call either method later, when the factory already has
  *     active sessions.
  * </ul>
+ * <p>
  * The {@code SessionFactory} exposes part of the information in the runtime
  * metamodel via an {@linkplain #getMetamodel() instance} of the JPA-defined
  * {@link jakarta.persistence.metamodel.Metamodel}. This object is sometimes

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

@@ -27,12 +27,14 @@
  *     checking, and
  * <li>nor do operations cascade to associated instances.
  * </ul>
+ * <p>
  * 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>
+ * <p>
  * Stateless sessions are vulnerable to data aliasing effects, due to the
  * lack of a first-level cache.
  * <p>

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

@@ -29,27 +29,28 @@
  * An {@code @Any} mapping would store the discriminator value identifying the concrete
  * type of {@code Payment} along with the state of the associated {@code Order}, instead
  * of storing it with the {@code Payment} entity itself.
- * <pre>{@code
+ * <pre>
  * interface Payment { ... }
  *
- * @Entity
+ * &#64;Entity
  * class CashPayment { ... }
  *
- * @Entity
+ * &#64;Entity
  * class CreditCardPayment { ... }
  *
- * @Entity
+ * &#64;Entity
  * class Order {
  *     ...
- *     @Any
- *     @JoinColumn(name="payment_id") //the foreign key column
- *     @Column(name="payment_type")   //the discriminator column
- *     @AnyDiscriminatorValue(discriminator="CASH", entity=CashPayment.class)
- *     @AnyDiscriminatorValue(discriminator="CREDIT", entity=CreditCardPayment.class)
+ *     &#64;Any
+ *     &#64;JoinColumn(name="payment_id") //the foreign key column
+ *     &#64;Column(name="payment_type")   //the discriminator column
+ *     &#64;AnyDiscriminatorValue(discriminator="CASH", entity=CashPayment.class)
+ *     &#64;AnyDiscriminatorValue(discriminator="CREDIT", entity=CreditCardPayment.class)
  *     Payment payment;
  *     ...
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * In this example, {@code Payment} is <em>not</em> be declared as an entity type, and
  * is not annotated {@link jakarta.persistence.Entity @Entity}. It might even be an
  * interface, or at most just a {@linkplain jakarta.persistence.MappedSuperclass mapped
@@ -74,6 +75,7 @@
  *         {@link AnyKeyJdbcTypeCode} specifies the type of the foreign key.
  *     <li>{@link jakarta.persistence.JoinColumn} specifies the foreign key column.
  * </ul>
+ * <p>
  * Of course, {@code Any} mappings are disfavored, except in extremely special cases,
  * since it's much more difficult to enforce referential integrity at the database
  * level.
@@ -92,6 +94,7 @@
 	 * <li>{@link FetchType#LAZY LAZY} allows the association to be fetched lazily, but
 	 *     this is possible only when bytecode enhancement is used.
 	 * </ul>
+	 * <p>
 	 * If not explicitly specified, the default is {@code EAGER}.
 	 */
 	FetchType fetch() default FetchType.EAGER;

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

@@ -35,6 +35,7 @@
  *        ...
  *    }
  * </pre>
+ * <p>
  * will initialize up to 100 unfetched {@code Product} proxies in each
  * trip to the database.
  * <p>
@@ -44,6 +45,7 @@
  *    &#64;BatchSize(size = 5) /
  *    Set&lt;Product&gt; getProducts() { ... };
  * </pre>
+ * <p>
  * will initialize up to 5 unfetched collections of {@code Product}s in
  * each SQL {@code select}.
  *

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

@@ -24,6 +24,7 @@
  *     given the expected data access patterns affecting the entity
  *     or collection.
  * </ul>
+ * <p>
  * This annotation should always be used in preference to the less
  * useful JPA-defined annotation {@link jakarta.persistence.Cacheable},
  * since JPA provides no means to specify anything about the semantics
@@ -34,17 +35,19 @@
  * cache inherit the cache belonging to the root entity.
  * <p>
  * For example, the following entity is eligible for caching:
- * <pre>{@code
- * @Entity
- * @Cache(usage = NONSTRICT_READ_WRITE)
+ * <pre>
+ * &#64;Entity
+ * &#64;Cache(usage = NONSTRICT_READ_WRITE)
  * public static class Person { ... }
- * }</pre>
+ * </pre>
+ * <p>
  * Similarly, this collection is cached:
- * <pre>{@code
- * @OneToMany(mappedBy = "person")
- * @Cache(usage = NONSTRICT_READ_WRITE)
- * private List<Phone> phones = new ArrayList<>();
- * }</pre>
+ * <pre>
+ * &#64;OneToMany(mappedBy = "person")
+ * &#64;Cache(usage = NONSTRICT_READ_WRITE)
+ * private List&lt;Phone&gt; phones = new ArrayList&lt;&gt;();
+ * </pre>
+ * <p>
  * Note that the second-level cache is disabled unless
  * {@value org.hibernate.cfg.AvailableSettings#CACHE_REGION_FACTORY}
  * is explicitly specified, and so, by default, this annotation has

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

@@ -26,6 +26,7 @@
  * <li>read extremely frequently, and
  * <li>written infrequently.
  * </ul>
+ * <p>
  * When an entity or collection is marked {@linkplain Cache cacheable},
  * it must indicate the policy which governs concurrent access to its
  * second-level cache, by selecting a {@code CacheConcurrencyStrategy}
@@ -108,6 +109,7 @@ public enum CacheConcurrencyStrategy {
 	 *     with something that might not quite be the latest
 	 *     version.
 	 * </ul>
+	 * <p>
 	 * This concurrency strategy is not compatible with
 	 * serializable transaction isolation.
 	 *

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

@@ -24,11 +24,9 @@
  * To enable cascade {@code LOCK}, use {@link Cascade @Cascade}, for
  * example:
  * <pre>
- * {@code
- * @OneToMany(mappedBy="parent")
- * @Cascade({PERSIST,REFRESH,REMOVE,LOCK})
- * Set<Child> children;
- * }
+ * &#64;OneToMany(mappedBy="parent")
+ * &#64;Cascade({PERSIST,REFRESH,REMOVE,LOCK})
+ * Set&lt;Child&gt; children;
  * </pre>
  *
  * @see Cascade

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

@@ -26,23 +26,22 @@
 @Retention(RUNTIME)
 public @interface CollectionId {
 	/**
-	 * The column containing the collection-id
+	 * The column containing the collection id.
 	 */
 	Column column() default @Column;
 
 	/**
-	 * Implementation for generating values
+	 * Implementation for generating values.
 	 *
 	 * @apiNote Mutually exclusive with {@link #generator()}
 	 */
 	Class<? extends IdentifierGenerator> generatorImplementation() default IdentifierGenerator.class;
 
 	/**
 	 * The generator name.
-	 *
-	 * Can specify either a built-in strategy ("sequence", e.g.)
-	 * or a named generatorIdentifierGenerator
-	 * ({@link jakarta.persistence.SequenceGenerator}, e.g.)
+	 * <p>
+	 * Can specify either a built-in strategy ({@code "sequence"}, for example)
+	 * or a named JPA id generator.
 	 *
 	 * @apiNote Mutually exclusive with {@link #generatorImplementation()}
 	 */

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

@@ -18,7 +18,7 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link JavaType} for describing the id of an id-bag mapping
+ * Form of {@link JavaType} for describing the id of an id-bag mapping.
  *
  * @since 6.0
  */

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

@@ -18,7 +18,7 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link org.hibernate.annotations.JdbcType} for describing the id of an id-bag mapping
+ * Form of {@link org.hibernate.annotations.JdbcType} for describing the id of an id-bag mapping.
  *
  * @since 6.0
  */

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

@@ -16,7 +16,7 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link JdbcTypeCode} for describing the id of an id-bag mapping
+ * Form of {@link JdbcTypeCode} for describing the id of an id-bag mapping.
  *
  * @since 6.0
  */

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

@@ -16,7 +16,7 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link Type} for describing the id of an id-bag mapping
+ * Form of {@link Type} for describing the id of an id-bag mapping.
  *
  * @since 6.0
  */

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

@@ -23,6 +23,7 @@
  *     <li>{@link Generated @Generated}, to populate an entity attribute with
  *         the defaulted value of a database column.
  * </ul>
+ * <p>
  * If {@code @Generated} is not used, a {@code default} value can cause state
  * held in memory to lose synchronization with the database.
  *