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 @@ package org.hibernate;
  *     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 @@ package org.hibernate;
  * <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 @@ import org.hibernate.type.Type;
  *         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 @@ public interface Interceptor {
 	 * <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.Clob;
 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 @@ import static java.util.Collections.unmodifiableSet;
  * <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 @@ import org.hibernate.internal.util.StringHelper;
  *     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 @@ import jakarta.persistence.criteria.CriteriaUpdate;
  * <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 @@ import jakarta.persistence.criteria.CriteriaUpdate;
  * 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}
+ * From {@linkplain FlushMode time to time}, a {@linkplain #flush() flush operation} is
- * operation, and synchronizes state held in memory with persistent state held in the
+ * triggered, and the session synchronizes state held in memory with persistent state
- * database by executing SQL {@code insert}, {@code update}, and {@code delete} statements.
+ * held in the database by executing SQL {@code insert}, {@code update}, and {@code delete}
- * Note that SQL statements are often not executed synchronously by the methods of the
+ * statements. Note that SQL statements are often not executed synchronously by the methods
- * {@code Session} interface. If synchronous execution of SQL is desired, the
+ * 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 @@ import jakarta.persistence.EntityManagerFactory;
  * 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 @@ import jakarta.persistence.EntityManagerFactory;
  * 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 @@ import jakarta.persistence.EntityManagerFactory;
  *     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 @@ package org.hibernate;
  *     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 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * 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
+ *     &#64;Any
- *     @JoinColumn(name="payment_id") //the foreign key column
+ *     &#64;JoinColumn(name="payment_id") //the foreign key column
- *     @Column(name="payment_type")   //the discriminator column
+ *     &#64;Column(name="payment_type")   //the discriminator column
- *     @AnyDiscriminatorValue(discriminator="CASH", entity=CashPayment.class)
+ *     &#64;AnyDiscriminatorValue(discriminator="CASH", entity=CashPayment.class)
- *     @AnyDiscriminatorValue(discriminator="CREDIT", entity=CreditCardPayment.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 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *         {@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 @@ public @interface Any {
 	 * <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 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *        ...
  *    }
  * </pre>
+ * <p>
  * will initialize up to 100 unfetched {@code Product} proxies in each
  * trip to the database.
  * <p>
@@ -44,6 +45,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *    &#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 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     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 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * cache inherit the cache belonging to the root entity.
  * <p>
  * For example, the following entity is eligible for caching:
- * <pre>{@code
+ * <pre>
- * @Entity
+ * &#64;Entity
- * @Cache(usage = NONSTRICT_READ_WRITE)
+ * &#64;Cache(usage = NONSTRICT_READ_WRITE)
  * public static class Person { ... }
- * }</pre>
+ * </pre>
+ * <p>
  * Similarly, this collection is cached:
- * <pre>{@code
+ * <pre>
- * @OneToMany(mappedBy = "person")
+ * &#64;OneToMany(mappedBy = "person")
- * @Cache(usage = NONSTRICT_READ_WRITE)
+ * &#64;Cache(usage = NONSTRICT_READ_WRITE)
- * private List<Phone> phones = new ArrayList<>();
+ * private List&lt;Phone&gt; phones = new ArrayList&lt;&gt;();
- * }</pre>
+ * </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 @@ import org.hibernate.cache.spi.access.AccessType;
  * <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 @@ import org.hibernate.ReplicationMode;
  * To enable cascade {@code LOCK}, use {@link Cascade @Cascade}, for
  * example:
  * <pre>
- * {@code
+ * &#64;OneToMany(mappedBy="parent")
- * @OneToMany(mappedBy="parent")
+ * &#64;Cascade({PERSIST,REFRESH,REMOVE,LOCK})
- * @Cascade({PERSIST,REFRESH,REMOVE,LOCK})
+ * Set&lt;Child&gt; children;
- * Set<Child> children;
- * }
  * </pre>
  *
  * @see Cascade

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

@@ -26,12 +26,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @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()}
 	 */
@@ -39,10 +39,9 @@ public @interface CollectionId {
 
 	/**
 	 * The generator name.
-	 *
+	 * <p>
-	 * Can specify either a built-in strategy ("sequence", e.g.)
+	 * Can specify either a built-in strategy ({@code "sequence"}, for example)
-	 * or a named generatorIdentifierGenerator
+	 * or a named JPA id generator.
-	 * ({@link jakarta.persistence.SequenceGenerator}, e.g.)
 	 *
 	 * @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.ElementType.METHOD;
 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.ElementType.METHOD;
 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.ElementType.METHOD;
 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.ElementType.METHOD;
 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 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     <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.
  *

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

@@ -22,15 +22,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <li>A {@link #write} expression must contain exactly one JDBC-style '?' placeholder.
  * <li>A {@link #read} expression may not contain JDBC-style placeholders.
  * </ul>
+ * <p>
  * For example:
  * <pre>
- * {@code
+ * &#64;Column(name="credit_card_num")
- * @Column(name="credit_card_num")
+ * &#64;ColumnTransformer(read="decrypt(credit_card_num)"
- * @ColumnTransformer(read="decrypt(credit_card_num)"
  *                    write="encrypt(?)")
  * String creditCardNumber;
- * }
  * </pre>
+ * <p>
  * A column transformer {@link #write} expression transforms the value of a persistent
  * attribute of an entity as it is being written to the database.
  * <ul>
@@ -43,6 +43,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     in-memory state of the Java entity instance should be considered unsynchronized
  *     with the database after every SQL {@code insert} or {@code update} is executed.
  * </ul>
+ * <p>
  * In the second scenario, we may ask Hibernate to resynchronize the in-memory state
  * with the database after each {@code insert} or {@code update} by annotating the
  * persistent attribute {@link Generated @Generated(event={INSERT,UPDATE}, writable=true)}.

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

@@ -32,6 +32,7 @@ import static org.hibernate.generator.EventType.UPDATE;
  * <li>{@link SourceType#DB source = DB} indicates that the database
  *     {@code current_timestamp} function should be used.
  * </ul>
+ * <p>
  * By default, the timestamp is generated by the database, which requires
  * an extra round trip to the database to fetch the generated value.
  * <p>

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

@@ -23,38 +23,39 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * Used in place of the JPA {@link jakarta.persistence.DiscriminatorColumn}.
  * <p>
  * For example, we might declare a supertype as follows:
- * <pre>{@code
+ * <pre>
- * @Entity
+ * &#64;Entity
- * @DiscriminatorFormula(discriminatorType = INTEGER,
+ * &#64;DiscriminatorFormula(discriminatorType = INTEGER,
  * 		value = "case when value1 is not null then 1 when value2 is not null then 2 end")
  * public abstract class AbstractChild {
- *     @Id
+ *     &#64;Id
- *     @GeneratedValue
+ *     &#64;GeneratedValue
  *     Integer id;
  *     ...
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * and then each concrete subclass must specify a matching discriminator value:
- * <pre>{@code
+ * <pre>
- * @Entity
+ * &#64;Entity
- * @DiscriminatorValue("1")
+ * &#64;DiscriminatorValue("1")
  * public class ConcreteChild1 extends AbstractChild {
- *     @Basic(optional = false)
+ *     &#64;Basic(optional = false)
- *     @Column(name = "VALUE1")
+ *     &#64;Column(name = "VALUE1")
  *     String value;
  *     ...
  * }
- * }</pre>
+ * </pre>
- * <pre>{@code
+ * <pre>
- * @Entity
+ * &#64;Entity
- * @DiscriminatorValue("2")
+ * &#64;DiscriminatorValue("2")
  * public class ConcreteChild2 extends AbstractChild {
- *     @Basic(optional = false)
+ *     &#64;Basic(optional = false)
- *     @Column(name = "VALUE2")
+ *     &#64;Column(name = "VALUE2")
  *     String value;
  *     ...
  * }
- * }</pre>
+ * </pre>
  *
  * @see Formula
  * @see DialectOverride.DiscriminatorFormula

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

@@ -22,6 +22,7 @@ import java.lang.annotation.Target;
  * <li>{@linkplain FetchMode#JOIN join fetching} is used for
  *     {@linkplain jakarta.persistence.FetchType#EAGER eager} fetching.
  * </ul>
+ * <p>
  * The default fetching strategy specified by this annotation may be
  * overridden in a given {@linkplain FetchProfile fetch profile}.
  *

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

@@ -37,6 +37,7 @@ public enum FetchMode {
 	 * <li>ensuring that the associated entity or collection may be
 	 *     retrieved from the {@linkplain Cache second-level cache}.
 	 * </ul>
+	 * <p>
 	 * This fetching strategy is, in principle, compatible with both
 	 * {@linkplain jakarta.persistence.FetchType#EAGER eager} and
 	 * {@linkplain jakarta.persistence.FetchType#LAZY lazy} fetching.

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

@@ -39,6 +39,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <li>an entity graph is explicit, and simply specifies that each path
  *     from the root of the graph should be fetched.
  * </ul>
+ * <p>
  * However, a fetch profile is not by nature rooted at any one particular
  * entity, and so {@code @FetchProfile} is not required to annotate the
  * entity classes it affects. It may even occur as a package-level

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

@@ -24,17 +24,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * For example, we might apply a filter named {@code Current} to
  * an entity like this:
  * <pre>
- * {@code
+ * &#64;Entity
- * @Entity
+ * &#64;Filter(name = "Current",
- * @Filter(name = "Current",
  *         deduceAliasInjectionPoints = false,
  *         condition = "{alias}.year = extract(year from current_date)")
  * class Course {
- *     @Id @GeneratedValue Long id;
+ *     &#64;Id &#64;GeneratedValue Long id;
  *     int year;
  *     ...
  * }
- * }
  * </pre>
  * <p>
  * If an entity or collection has no {@code @Filter} annotation

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

@@ -28,30 +28,27 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <p>
  * For example, if a filter is declared as follows:
  * <pre>
- * {@code
+ * &#64;FilterDef(name = "Current",
- * @FilterDef(name = "Current",
  *            defaultCondition = "status<>'DELETED'")
  * package org.hibernate.domain;
- * }
  * </pre>
+ * <p>
  * Then the filter may be applied to an entity type like this:
  * <pre>
- * {@code
+ * &#64;Entity
- * @Entity
+ * &#64;Filter(name = "Current")
- * @Filter(name = "Current")
  * class Record {
- *     @Id @GeneratedValue Long id;
+ *     &#64;Id @GeneratedValue Long id;
- *     @Enumerated(STRING) Status status;
+ *     &#64;Enumerated(STRING) Status status;
  *     ...
  * }
- * }
  * </pre>
  * <p>
  * At runtime, a filter may be enabled in a particular session by
  * calling {@link org.hibernate.Session#enableFilter(String)},
  * passing the name of the filter, and then setting its parameters.
  * <pre>
- * {@code session.enableFilter("Current");}
+ * session.enableFilter("Current");
  * </pre>
  *
  * @author Matthew Inger

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

@@ -19,26 +19,26 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * A {@code Formula} mapping defines a "derived" attribute, whose state is determined
  * from other columns and functions when an entity is read from the database.
  *
- * <pre><code>
+ * <pre>
- *     // perform calculations using SQL operators
+ * // perform calculations using SQL operators
- *     &#064;Formula("sub_total + (sub_total * tax)")
+ * &#64;Formula("sub_total + (sub_total * tax)")
- *     long getTotalCost() { ... }
+ * long getTotalCost() { ... }
- * </code></pre>
+ * </pre>
- *
- * <pre><code>
- *     // call native SQL functions
- *     &#064;Formula("upper(substring(middle_name, 1))")
- *     Character getMiddleInitial() { ... }
- * </code></pre>
  *
+ * <pre>
+ * // call native SQL functions
+ * &#64;Formula("upper(substring(middle_name, 1))")
+ * Character getMiddleInitial() { ... }
+ * </pre>
+ * <p>
  * {@link ColumnTransformer} is an alternative, allowing the use of native SQL to
  * read and write values.
  *
- * <pre><code>
+ * <pre>
- *     // it might be better to use @ColumnTransformer in this case
+ * // it might be better to use &#64;ColumnTransformer in this case
- *     &#064;Formula("decrypt(credit_card_num)")
+ * &#064;Formula("decrypt(credit_card_num)")
- *     String getCreditCardNumber() { ... }
+ * String getCreditCardNumber() { ... }
- * </code></pre>
+ * </pre>
  *
  * @see ColumnTransformer
  * @see DiscriminatorFormula

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

@@ -39,6 +39,7 @@ import static org.hibernate.generator.EventType.INSERT;
  *     property of the entity, or {@linkplain #writable() transforms} the
  *     value currently assigned to the annotated property.
  * </ul>
+ * <p>
  * On the other hand:
  * <ul>
  * <li>for identity/autoincrement columns mapped to an identifier property,
@@ -85,6 +86,7 @@ public @interface Generated {
 	 *     selected after each SQL {@code insert} or {@code update}
 	 *     statement is executed.
 	 * </ul>
+	 * 
 	 * @deprecated use {@link #event()}
 	 */
 	@Deprecated(since = "6.2")

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

@@ -36,21 +36,23 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     to specify the {@link #name()} of the generator defined using this
  *     annotation.
  * </ul>
+ * <p>
  * If neither {@link #type} not {@link #strategy} is specified, Hibernate asks
  * {@linkplain org.hibernate.dialect.Dialect#getNativeIdentifierGeneratorStrategy
  * the dialect} to decide an appropriate strategy. This is equivalent to using
  * {@link jakarta.persistence.GenerationType#AUTO AUTO} in JPA.
  * <p>
  * For example, if we define a generator using:
- * <pre>{@code
+ * <pre>
- * @GenericGenerator(name = "custom-generator",
+ * &#64;GenericGenerator(name = "custom-generator",
  *                   type = org.hibernate.eg.CustomStringGenerator.class)
  * }</pre>
+ * <p>
  * Then we may make use of it by annotating an identifier field as follows:
- * <pre>{@code
+ * <pre>
- * @Id @GeneratedValue(generator = "custom-generator")
+ * &#64;Id &#64;GeneratedValue(generator = "custom-generator")
  * private String id;
- * }</pre>
+ * </pre>
  * <p>
  * The disadvantage of this approach is the use of stringly-typed names. An
  * alternative, completely typesafe, way to declare a generator and associate

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

@@ -22,7 +22,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * way to work with customized identifier generation in Hibernate.
  * <p>
  * For example, if we have a custom identifier generator:
- * <pre>{@code
+ * <pre>
  * public class CustomSequenceGenerator implements BeforeExecutionGenerator {
  *     public CustomSequenceGenerator(CustomSequence config, Member annotatedMember,
  *                                    CustomIdGeneratorCreationContext context) {
@@ -30,23 +30,26 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     }
  *     ...
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * Then we may also define an annotation which associates this generator with
  * an entity and supplies configuration parameters:
- * <pre>{@code
+ * <pre>
- * @IdGeneratorType(CustomSequenceGenerator.class)
+ * &#64;IdGeneratorType(CustomSequenceGenerator.class)
- * @Retention(RUNTIME) @Target({METHOD,FIELD})
+ * &#64;Retention(RUNTIME) @Target({METHOD,FIELD})
  * public @interface CustomSequence {
  *     String name();
  *     int startWith() default 1;
  *     int incrementBy() default 50;
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * and we may use it as follows:
- * <pre>{@code
+ * <pre>
- * @Id @CustomSequence(name = "mysequence", startWith = 0)
+ * &#64;Id &#64;CustomSequence(name = "mysequence", startWith = 0)
  * private Integer id;
- * }</pre>
+ * </pre>
+ * <p>
  * We did not use the JPA-defined {@link jakarta.persistence.GeneratedValue}
  * here, since that API is designed around the use of stringly-typed names.
  * The {@code @CustomSequence} annotation itself implies that {@code id} is
@@ -59,6 +62,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <li>the id generator class has a constructor with the same signature as
  *     {@link AnnotationBasedGenerator#initialize}.
  * </ul>
+ * <p>
  * For a more complete example, see the annotation {@link UuidGenerator} and
  * the corresponding generator class {@link org.hibernate.id.uuid.UuidGenerator}.
  * <p>

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

@@ -30,6 +30,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     lazy fields at once. This annotation provides control over that
  *     behavior.
  * </ul>
+ * <p>
  * A fetch group identifies a set of related attributes that should be loaded
  * together when any one of them is accessed. By default, all non-collection
  * attributes belong to a single fetch group named {@code "DEFAULT"}. The

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

@@ -76,6 +76,7 @@ public enum LazyToOneOption {
 	 * <li>Bytecode enhancement is required. If the class is not
 	 *     enhanced, this option is equivalent to {@link #PROXY}.
 	 * </ul>
+	 * <p>
 	 * Hibernate does not support this setting for polymorphic
 	 * associations, and instead falls back to {@link #PROXY}.
 	 *

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

@@ -20,6 +20,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <li>When an element is written to the database, the base value is added to
  *     the list or array index to determine the order column value.
  *</ul>
+ * <p>
  * By default, the base value for an order column is zero, as required by JPA.
  * <p>
  * This annotation is usually used in conjunction with the JPA-defined

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

@@ -18,7 +18,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link JavaType} for describing the column mapping for the index of a List or array
+ * Form of {@link JavaType} for describing the column mapping
+ * for the index of a {@code List} or array.
  *
  * @since 6.0
  */

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

@@ -16,7 +16,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link org.hibernate.annotations.JdbcType} for describing the column mapping for the index of a List or array
+ * Form of {@link org.hibernate.annotations.JdbcType} for describing
+ * the column mapping for the index of a {@code List} or array.
  *
  * @since 6.0
  */

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

@@ -16,7 +16,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link JdbcTypeCode} for describing the column mapping for the index of a List or array
+ * Form of {@link JdbcTypeCode} for describing the column mapping
+ * for the index of a {@code List} or array.
  *
  * @since 6.0
  */

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

@@ -27,18 +27,19 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * entities.
  * <p>
  * For example:
- * <pre>{@code
+ * <pre>
- * @ManyToAny
+ * &#64;ManyToAny
- * @Column(name = "property_type")
+ * &#64;Column(name = "property_type")
- * @AnyKeyJavaClass(Long.class)
+ * &#64;AnyKeyJavaClass(Long.class)
- * @AnyDiscriminatorValue(discriminator = "S", entity = StringProperty.class)
+ * &#64;AnyDiscriminatorValue(discriminator = "S", entity = StringProperty.class)
- * @AnyDiscriminatorValue(discriminator = "I", entity = IntegerProperty.class)
+ * &#64;AnyDiscriminatorValue(discriminator = "I", entity = IntegerProperty.class)
- * @JoinTable(name = "repository_properties",
+ * &#64;JoinTable(name = "repository_properties",
  *            joinColumns = @JoinColumn(name = "repository_id"),
  *            inverseJoinColumns = @JoinColumn(name = "property_id"))
- * @Cascade(PERSIST)
+ * &#64;Cascade(PERSIST)
- * private List<Property<?>> properties = new ArrayList<>();
+ * private List&lt;Property&lt;?&gt;&gt; properties = new ArrayList&lt;&gt;();
- * }</pre>
+ * </pre>
+ * <p>
  * In this example, {@code Property} is not required to be an entity type,
  * it might even just be an interface, but its subtypes {@code StringProperty}
  * and {@code IntegerProperty} must be entity classes with the same identifier

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

@@ -18,7 +18,7 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Form of {@link Type} for use with map-keys
+ * Form of {@link Type} for use with map keys.
  *
  * @since 6.0
  */

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

@@ -23,8 +23,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * Specifies a {@link MutabilityPlan} for a basic value mapping.
  * <ul>
  *     <li>
- *         When applied to a Map-valued attribute, describes the
+ *         When applied to a {@code Map}-valued attribute, describes
- *         {@code Map} value. Use {@link MapKeyMutability} to
+ *         the {@code Map} value. Use {@link MapKeyMutability} to
  *         describe the key instead.
  *     </li>
  *     <li>
@@ -44,15 +44,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *         {@link ManyToAny}), describes the discriminator value.
  *     </li>
  * </ul>
- *
+ * <p>
  * Resolved as a {@link org.hibernate.resource.beans.spi.ManagedBean}.
- *
+ * <p>
- * See <a href="package-summary.html#basic-value-mapping">basic-value-mapping</a> for a
+ * See <a href="package-summary.html#basic-value-mapping">basic-value-mapping</a>
- * high-level discussion of basic value mapping.
+ * for a high-level discussion of basic value mapping.
  *
  * @apiNote Valid on {@link ElementType#TYPE} in very limited cases.
- * At the moment it is only supported on implementations of
+ *          At the moment it is only supported on implementations of
- * {@link jakarta.persistence.AttributeConverter}.
+ *          {@link jakarta.persistence.AttributeConverter}.
  *
  * @see Immutable
  *

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

@@ -24,47 +24,49 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * user of the system. This is the <em>natural id</em> of the entity.
  * <p>
  * A natural id may be a single field or property of the entity:
- * <pre>{@code
+ * <pre>
- * @Entity
+ * &#64;Entity
- * @Cache @NaturalIdCache
+ * &#64;Cache &#64;NaturalIdCache
  * class Person {
  *
  *     //synthetic id
- *     @GeneratedValue @Id
+ *     &#64;GeneratedValue @Id
  *     Long id;
  *
- *     @NotNull
+ *     &#64;NotNull
  *     String name;
  *
  *     //simple natural id
- *     @NotNull @NaturalId
+ *     &#64;NotNull @NaturalId
  *     String ssn;
  *
  *     ...
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * or it may be a composite value:
- * <pre>{@code
+ * <pre>
- * @Entity
+ * &#64;Entity
- * @Cache @NaturalIdCache
+ * &#64;Cache &#64;NaturalIdCache
  * class Vehicle {
  *
  *     //synthetic id
- *     @GeneratedValue @Id
+ *     &#64;GeneratedValue @Id
  *     Long id;
  *
  *     //composite natural id
  *
- *     @Enumerated
+ *     &#64;Enumerated
- *     @NotNull @NaturalId
+ *     &#64;NotNull &#64;NaturalId
  *     Region region;
  *
- *     @NotNull @NaturalId
+ *     &#64;NotNull &#64;NaturalId
  *     String registration;
  *
  *     ...
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * The {@link org.hibernate.Session} interface offers several methods
  * that allow an entity instance to be retrieved by its
  * {@linkplain org.hibernate.Session#bySimpleNaturalId(Class) simple}

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

@@ -30,6 +30,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <li>{@link NotFoundAction#IGNORE} specifies that this situation should
  *     be tolerated and treated as if the foreign key were null.
  * </ul>
+ * <p>
  * Note that this annotation has the side effect of making a to-one
  * association non-lazy. It does not affect the laziness of a many-to-many
  * association.

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

@@ -22,6 +22,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     entity instance, or
  * <li>{@linkplain OptimisticLockType#ALL all fields} of the entity.
  * </ul>
+ * <p>
  * An optimistic lock is usually checked by including a restriction in a
  * SQL {@code update} or {@code delete} statement. If the database reports
  * that zero rows were updated, it is inferred that another transaction

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

@@ -23,7 +23,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * is neither an entity class nor a mapped superclass. The
  * query will return all entities which inherit the type.
  * For example, the query
- *     <pre>{@code from java.lang.Object}</pre>
+ * <pre>from java.lang.Object</pre>
+ * <p>
  * will return every entity mapped by Hibernate!
  * <p>
  * This can be thought of as allowing a sort of "poor man's"

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

@@ -20,7 +20,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * generated by Hibernate when an entity or collection row is deleted from the
  * database.
  * <p>
- * The given {@link #sql SQL statement} must have exactly the number of JDBC
+ * The given {@linkplain #sql SQL statement} must have exactly the number of JDBC
  * {@code ?} parameters that Hibernate expects, in the exact order Hibernate
  * expects. The primary key columns come before the version column if the
  * entity is versioned.

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

@@ -20,10 +20,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * generated by Hibernate when an entity or collection row is inserted in the
  * database.
  * <p>
- * The given {@link #sql SQL statement} must have exactly the number of JDBC
+ * The given {@linkplain #sql SQL statement} must have exactly the number of JDBC
  * {@code ?} parameters that Hibernate expects, that is, one for each column
  * mapped by the entity, in the exact order Hibernate expects. In particular,
- * the {@link jakarta.persistence.Id primary key} columns must come last.
+ * the {@linkplain jakarta.persistence.Id primary key} columns must come last.
  * <p>
  * If a column should <em>not</em> be written as part of the insert statement,
  * and has no corresponding JDBC parameter in the custom SQL, it must be mapped

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

@@ -20,11 +20,11 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * generated by Hibernate when an entity or collection row is updated in the
  * database.
  * <p>
- * The given {@link #sql SQL statement} must have exactly the number of JDBC
+ * The given {@linkplain #sql SQL statement} must have exactly the number of JDBC
  * {@code ?} parameters that Hibernate expects, that is, one for each column
  * mapped by the entity, in the exact order Hibernate expects. In particular,
- * the {@link jakarta.persistence.Id primary key} columns come last unless
+ * the {@linkplain jakarta.persistence.Id primary key} columns come last unless
- * the entity is {@link jakarta.persistence.Version versioned}, in which case
+ * the entity is {@linkplain jakarta.persistence.Version versioned}, in which case
  * there must be a second JDBC parameter for the version column, which comes
  * after the primary key.
  * <p>

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

@@ -20,7 +20,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * Sorting is performed in memory, by Java's {@link java.util.TreeSet} or {@link java.util.TreeMap},
  * and is maintained by any operation that mutates the collection.
  * <ul>
- * <li>Use {@link SortNatural} in its {@link java.util.Comparator natural order}.
+ * <li>Use {@link SortNatural} to sort by {@linkplain java.util.Comparator natural order}.
  * <li>Use {@link jakarta.persistence.OrderBy} to order using an expression written in HQL.
  * <li>Use {@link OrderBy} to order using an expression written in native SQL.
  * </ul>

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

@@ -27,14 +27,14 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <li>{@link SourceType#DB} indicates that the database
  *     {@code current_timestamp} function should be used.
  * </ul>
+ * <p>
  * For example, the following timestamp is generated by the
  * database:
  * <pre>
- * {@code
+ * &#64;Version &#64;Source(DB)
- * @Version @Source(DB)
  * private LocalDateTime version;
- * }
  * </pre>
+ * <p>
  * This annotation is always used in conjunction with the JPA
  * {@link jakarta.persistence.Version @Version} annotation.
  *

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

@@ -25,21 +25,19 @@ import static java.lang.annotation.ElementType.METHOD;
  * <p>
  * For example:
  * <pre>
- * {@code
+ * &#64;Entity
- * @Entity
  * public class Person {
  *
- *     @Column(name = "birth_timestamp")
+ *     &#64;Column(name = "birth_timestamp")
- *     @TimeZoneColumn(name = "birth_zone")
+ *     &#64;TimeZoneColumn(name = "birth_zone")
- *     @TimeZoneStorage(COLUMN)
+ *     &#64;TimeZoneStorage(COLUMN)
  *     public OffsetDateTime birthDate;
  *
- *     @TimeZoneStorage(NATIVE)
+ *     &#64;TimeZoneStorage(NATIVE)
  *     public OffsetDateTime registrationDate;
  *
  *     ...
- *   }
+ * }
- *}
  * </pre>
  *
  * @author Christian Beikov

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

@@ -29,6 +29,7 @@ import org.hibernate.dialect.Dialect;
  *     {@linkplain java.time.ZonedDateTime#getZone() zone} in which the
  *     instant is represented.
  * </ul>
+ * <p>
  * We must also consider the physical representation of the zoned datetime
  * in the database table.
  * <p>
@@ -43,6 +44,7 @@ import org.hibernate.dialect.Dialect;
  *     so that datetimes retrieved from the database will be represented in
  *     UTC.
  * </ul>
+ * <p>
  * When this default strategy is not appropriate, recommended alternatives
  * are:
  * <ul>
@@ -82,6 +84,7 @@ public enum TimeZoneStorageType {
 	 * <li>passes them through in the JVM default time zone
 	 *    otherwise.
 	 * </ul>
+	 * <p>
 	 * Provided partly for backward compatibility with older
 	 * versions of Hibernate
 	 */

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

@@ -26,23 +26,27 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     applied to various properties and fields, or
  * <li>by default, via a {@linkplain TypeRegistration registration}.
  * </ul>
+ * <p>
  * For example, as an alternative to:
- * <pre>{@code
+ * <pre>
- * @Type(MonetaryAmountUserType.class)
+ * &#64;Type(MonetaryAmountUserType.class)
  * BigDecimal amount;
- * }</pre>
+ * </pre>
+ * <p>
  * we may define an annotation type:
- * <pre>{@code
+ * <pre>
- * @Retention(RUNTIME)
+ * &#64;Retention(RUNTIME)
- * @Target({METHOD,FIELD})
+ * &#64;Target({METHOD,FIELD})
- * @Type(MonetaryAmountUserType.class)
+ * &#64;Type(MonetaryAmountUserType.class)
  * public @interface MonetaryAmount {}
- * }</pre>
+ * </pre>
+ * <p>
  * and then write:
- * <pre>{@code
+ * <pre>
- * @MonetaryAmount
+ * &#64;MonetaryAmount
  * BigDecimal amount;
- * }</pre>
+ * </pre>
+ * <p>
  * which is much cleaner.
  * <p>
  * The use of a {@code UserType} is usually mutually exclusive with the

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

@@ -25,22 +25,30 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * best way to work with customized value generation in Hibernate.
  * <p>
  * For example, if we have a custom value generator:
- * <pre>{@code
+ * <pre>
  * public class SKUGeneration
- *         implements InMemoryValueGenerationStrategy,
+ *         implements BeforeExecutionGenerator {
- *                    ValueGenerator<String> {
+ *     public SKUGeneration(SKU sku, Member annotatedMember,
+ *                          GeneratorCreationContext context) {
+ *         ...
+ *     }
  *     ...
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * Then we may also define an annotation which associates this generator with
  * a field or property of an entity and supplies configuration parameters:
- * <pre>{@code
+ * <pre>
- * @ValueGenerationType(generatedBy = SKUGeneration.class)
+ * &#64;ValueGenerationType(generatedBy = SKUGeneration.class)
- * @Retention(RUNTIME) @Target({METHOD,FIELD})
+ * &#64;Retention(RUNTIME) &#64;Target({METHOD,FIELD})
- * public @interface SKU {}
+ * public &#64;interface SKU {}
- * }</pre>
+ * </pre>
+ * <p>
  * and we may use it as follows:
- * <pre>{@code @SKU String sku;}</pre>
+ * <pre>
+ * &#64;SKU String sku;
+ * </pre>
+ * <p>
  * No more than one generator annotation may be placed on a given property.
  * <p>
  * Adding a generator annotation to an entity property causes the value of the
@@ -55,6 +63,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <li>an {@link OnExecutionGenerator}, for values which are generated by the
  *     database.
  * </ul>
+ * <p>
  * A generator annotation may have members, which are used to configure the
  * value generator, if either:
  * <ul>
@@ -62,6 +71,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <li>the value generator class has a constructor with the same signature as
  *     {@link AnnotationBasedGenerator#initialize}.
  * </ul>
+ * <p>
  * There are several excellent examples of the use of this machinery right
  * here in this package. {@link TenantId} and its corresponding generator
  * {@link TenantIdGeneration} are a good place to start.

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

@@ -20,22 +20,24 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * <p>
  * For example, {@code @Where} could be used to hide entity instances which
  * have been soft-deleted, either for the entity class itself:
- * <pre>{@code
+ * <pre>
- * @Entity
+ * &#64;Entity
- * @Where(clause = "status <> 'DELETED'")
+ * &#64;Where(clause = "status &lt;&gt; 'DELETED'")
  * class Document {
  *     ...
- *     @Enumerated(STRING)
+ *     &#64;Enumerated(STRING)
  *     Status status;
  *     ...
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * or, at the level of an association to the entity:
- * <pre>{@code
+ * <pre>
- * @OneToMany(mappedBy = "owner")
+ * &#64;OneToMany(mappedBy = "owner")
- * @Where(clause = "status <> 'DELETED'")
+ * &#64;Where(clause = "status &lt;&gt; 'DELETED'")
- * List<Document> documents;
+ * List&lt;Document&gt; documents;
- * }</pre>
+ * </pre>
+ * <p>
  * By default, {@code @Where} restrictions declared for an entity are not
  * applied when loading a collection of that entity type. This behavior is
  * controlled by:

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

@@ -12,12 +12,13 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Specifies a restriction written in native SQL to add to the generated
+ * Specifies a restriction written in native SQL to add to the generated SQL
- * SQL when querying the {@link jakarta.persistence.JoinTable join table}
+ * when querying the {@linkplain jakarta.persistence.JoinTable join table}
  * of a collection.
  * <p>
- * For example, {@code @Where("status <> 'DELETED'")} could be used to hide
+ * For example, <code>&#64;Where("status &lt;&gt; 'DELETED'")</code> could be
- * associations which have been soft-deleted from an association table.
+ * used to hide associations which have been soft-deleted from an association
+ * table.
  *
  * @author Emmanuel Bernard
  *

hibernate-core/src/main/java/org/hibernate/annotations/package-info.java

@@ -8,39 +8,53 @@
 /**
  * A set of mapping annotations which extend the O/R mapping annotations defined by JPA.
  *
- * <h2 id="basic-value-mapping">Basic value mapping</h2>
+ * <h2 id="basic-value-mapping">Basic value type mappings</h2>
  *
- * Hibernate supports two approaches to defining a mapping strategy for basic values:
+ * JPA supports a very limited set of built-in {@linkplain jakarta.persistence.Basic basic}
+ * types, and provides only {@linkplain jakarta.persistence.AttributeConverter converters}
+ * as a solution when the built-in types are insufficient.
+ * <p>
+ * By contrast, Hibernate has an embarrassingly rich set of abstractions for modelling
+ * "basic" types, which can be initially confusing. Note that the venerable interface
+ * {@link org.hibernate.type.Type} abstracts over all sorts of field and property types,
+ * not only basic types. In modern Hibernate, programs should avoid directly implementing
+ * this interface.
+ * <p>
+ * Instead, a program should use either a "compositional" basic type, or in more extreme
+ * cases, a {@code UserType}.
  * <ul>
- *     <li>
+ * <li>
- *         A "compositional" approach using a combination of the following influencers for
+ *     A basic type is a composition of a {@link org.hibernate.type.descriptor.java.JavaType}
- *         various parts of mapping<ul>
+ *     with a {@link org.hibernate.type.descriptor.jdbc.JdbcType}, and possibly a JPA
- *             <li>{@link org.hibernate.annotations.JavaType}</li>
+ *     {@link jakarta.persistence.AttributeConverter}, and the process of composition is
- *             <li>{@link org.hibernate.annotations.JdbcType}</li>
+ *     usually somewhat implicit. A program may influence the choice of {@code JavaType}
- *             <li>{@link org.hibernate.annotations.JdbcTypeCode}</li>
+ *     or {@code JdbcType} using any of the following annotations:
- *             <li>{@link org.hibernate.annotations.Mutability}</li>
+ *     <ul>
- *             <li>{@link jakarta.persistence.AttributeConverter} / {@link jakarta.persistence.Convert}</li>
+ *     <li>{@link org.hibernate.annotations.JavaType}
- *             <li>{@link jakarta.persistence.Lob}</li>
+ *     <li>{@link org.hibernate.annotations.JdbcType}
- *             <li>{@link jakarta.persistence.Enumerated}</li>
+ *     <li>{@link org.hibernate.annotations.JdbcTypeCode}
- *             <li>{@link jakarta.persistence.Temporal}</li>
+ *     <li>{@link org.hibernate.annotations.Mutability}
- *             <li>{@link org.hibernate.annotations.Nationalized}</li>
+ *     <li>{@link jakarta.persistence.Convert}
- *         </ul>
+ *     <li>{@link jakarta.persistence.Lob}
- *         Note that {@link org.hibernate.annotations.JavaType}, {@link org.hibernate.annotations.JdbcType},
+ *     <li>{@link jakarta.persistence.Enumerated}
- *         {@link org.hibernate.annotations.JdbcTypeCode} and {@link org.hibernate.annotations.Mutability}
+ *     <li>{@link jakarta.persistence.Temporal}
- *         all have specialized forms for the various model parts such as map-key, list-index, (id-bag)
+ *     <li>{@link org.hibernate.annotations.Nationalized}
- *         collection-id, etc.
+ *     </ul>
- *     </li>
+ *     Note that {@link org.hibernate.annotations.JavaType}, {@link org.hibernate.annotations.JdbcType},
- *     <li>
+ *     {@link org.hibernate.annotations.JdbcTypeCode} and {@link org.hibernate.annotations.Mutability}
- *          Contracted via the {@link org.hibernate.usertype.UserType} interface and specified using
+ *     all come in specialized flavors for handling map keys, list indexes, and so on.
- *          {@link org.hibernate.annotations.Type}.
+ * <li>
- *          As with the compositional approach, there are model-part specific annotations for specifying
+ *     Alternatively, a program may implement the {@link org.hibernate.usertype.UserType}
- *          custom-types as well.
+ *     interface and associate it with a field or property explicitly using the
+ *     {@link org.hibernate.annotations.Type @Type} annotation, or implicitly using the
+ *     {@link org.hibernate.annotations.TypeRegistration @TypeRegistration} annotation.
+ *     There are some specialized flavors of the {@code @Type} annotation too.
  *     </li>
  * </ul>
- * These two approaches are not intended to be mixed. Specifying a custom-type takes precedence over
- * the compositional approach. Although the compositional approach is recommended, both forms are
- * fully supported.
  * <p>
- * Please see the user guide for a more in-depth discussion.
+ * These two approaches cannot be used together. A {@code UserType} always takes precedence
+ * over the compositional approach.
+ * <p>
+ * Please see the User Guide for a more in-depth discussion.
  */
 package org.hibernate.annotations;

hibernate-core/src/main/java/org/hibernate/boot/archive/spi/ArchiveDescriptor.java

@@ -13,7 +13,7 @@ package org.hibernate.boot.archive.spi;
  *     <li>an exploded directory</li>
  *     <li>etc</li>
  * </ul>
- * <p/>
+ * <p>
  * Used mainly for scanning purposes via {@linkplain #visitArchive visitation}
  *
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/boot/model/internal/BinderHelper.java

@@ -119,6 +119,7 @@ public class BinderHelper {
 	 *     the model that aggregates these properties and is considered
 	 *     the target of the association.
 	 * </ul>
+	 * <p>
 	 * Certain limitations arise from the way this solution is currently
 	 * implemented: for example, if a referenced column belongs to a
 	 * property of an {@code @Embeddable}, then every column of that

hibernate-core/src/main/java/org/hibernate/boot/model/internal/ComponentPropertyHolder.java

@@ -35,7 +35,7 @@ import static org.hibernate.boot.model.internal.HCANNHelper.hasAnnotation;
 import static org.hibernate.internal.util.StringHelper.isEmpty;
 
 /**
- * PropertyHolder for composites (Embeddable/Embedded).
+ * {@link PropertyHolder} for composites (Embeddable/Embedded).
  * <p>
  * To facilitate code comments, I'll often refer to this example:
  * <pre>
@@ -56,7 +56,7 @@ import static org.hibernate.internal.util.StringHelper.isEmpty;
  *         public Address homeAddress;
  *     }
  * </pre>
- *
+ * <p>
  * As you can see, lots of ways to specify the conversion for embeddable attributes :(
  *
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/boot/model/naming/PhysicalNamingStrategy.java

@@ -19,6 +19,7 @@ import org.hibernate.engine.jdbc.env.spi.JdbcEnvironment;
  *     <li>A <em>logical name</em> is a name used to within annotations of Java
  *     code and XML mapping documents.
  * </ul>
+ * <p>
  * Logical names provide an additional level of indirection between the mappings
  * and the database schema, and a {@code PhysicalNamingStrategy} even allows the
  * use of more "natural" naming within the mappings in cases where the relational

hibernate-core/src/main/java/org/hibernate/boot/model/relational/Database.java

@@ -91,13 +91,13 @@ public class Database {
 	}
 
 	/**
-	 * Wrap the raw name of a database object in it's Identifier form accounting for quoting from
+	 * Wrap the raw name of a database object in its Identifier form accounting for quoting from
 	 * any of:<ul>
 	 *     <li>explicit quoting in the name itself</li>
 	 *     <li>global request to quote all identifiers</li>
 	 * </ul>
-	 * <p>
+	 *
-	 * NOTE : quoting from database keywords happens only when building physical identifiers
+	 * @implNote Quoting from database keywords happens only when building physical identifiers.
 	 *
 	 * @param text The raw object name
 	 *

hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/RelationalValueSourceContainer.java

@@ -17,10 +17,10 @@ import java.util.List;
  *     <li>plural attribute mappings</li>
  *     <li>etc</li>
  * </ul>
- *
+ * <p>
  * Not only does it provide access to the relational value sources ({@link #getRelationalValueSources()}, it also defines
  * contextual information for those sources in terms of default values.
- *
+ * <p>
  * See {@link RelationalValueSource} for additional details.
  *
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/cache/spi/DomainDataRegion.java

@@ -18,12 +18,14 @@ import org.hibernate.metamodel.model.domain.NavigableRole;
  * <li>the destructured state of entity instances and collections, and
  * <li>mappings from natural id to primary key.
  * </ul>
+ * <p>
  * This type of data has:
  * <ul>
  * <li>key and value wrapping that should to be applied, and
  * <li>defined policies for managing concurrent data access, possibly
  *     including some form of locking.
  * </ul>
+ * <p>
  * These behaviors are defined by an instance of {@link EntityDataAccess},
  * {@link CollectionDataAccess}, or {@link NaturalIdDataAccess}).
  *

hibernate-core/src/main/java/org/hibernate/cache/spi/RegionFactory.java

@@ -29,11 +29,13 @@ import org.hibernate.service.spi.Stoppable;
  * <li>{@linkplain #buildTimestampsRegion timestamps} used to
  *     determine when a cached query result set is stale.
  * </ul>
+ * <p>
  * Implementors should define a constructor in one of two forms:
  * <ul>
  * <li>{@code MyRegionFactoryImpl(java.util.Properties)}</li>
  * <li>{@code MyRegionFactoryImpl()}</li>
  * </ul>
+ * <p>
  * Use the first when we need to read config properties prior to
  * {@link #start} being called.
  * <p>

hibernate-core/src/main/java/org/hibernate/cache/spi/access/NaturalIdDataAccess.java

@@ -18,6 +18,7 @@ import org.hibernate.persister.entity.EntityPersister;
  *     <li><b>DELETES</b> : {@link #lockItem} -> {@link #remove} -> {@link #unlockItem}</li>
  *     <li><b>LOADS</b> : {@link #putFromLoad}</li>
  * </ul>
+ * <p>
  * Note the special case of <b>UPDATES</b> above.  Because the cache key itself has changed here we need to remove the
  * old entry as well
  * <p>

hibernate-core/src/main/java/org/hibernate/cache/spi/access/package-info.java

@@ -24,6 +24,7 @@
  *     item.
  * </li>
  * </ul>
+ * <p>
  * The <i>asynchronous</i> access strategies are: {@link org.hibernate.cache.spi.access.AccessType#READ_ONLY read-only},
  * {@link org.hibernate.cache.spi.access.AccessType#READ_WRITE read-write} and
  * {@link org.hibernate.cache.spi.access.AccessType#NONSTRICT_READ_WRITE nonstrict-read-write}.  The only

hibernate-core/src/main/java/org/hibernate/cache/spi/support/package-info.java

@@ -22,6 +22,7 @@
  *     <li>{@link org.hibernate.cache.spi.support.RegionFactoryTemplate#createTimestampsRegionStorageAccess}
  *     </ul>
  * </ol>
+ * <p>
  * Voila! Functioning cache provider.
  * <p>
  * The preferred approach to "provide an integration" is through a custom

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

@@ -401,6 +401,7 @@ public interface AvailableSettings {
 	 *     <li>an instance of {@link javax.sql.DataSource}, or
 	 *     <li>a JNDI name under which to obtain the {@link javax.sql.DataSource}.
 	 * </ul>
+	 * <p>
 	 * For JNDI names, see also {@link #JNDI_CLASS}, {@link #JNDI_URL}, {@link #JNDI_PREFIX}, etc.
 	 *
 	 * @see javax.sql.DataSource
@@ -459,6 +460,7 @@ public interface AvailableSettings {
 	 *     <li>a {@link Class} representing a class that extends {@code Dialect}, or
 	 *     <li>the name of a class that extends {@code Dialect}.
 	 * </ul>
+	 * <p>
 	 * By default, Hibernate will attempt to automatically determine the dialect from the
 	 * {@linkplain #URL JDBC URL} and JDBC metadata, so this setting is not usually necessary.
 	 *
@@ -817,6 +819,7 @@ public interface AvailableSettings {
 	 *     <li>{@code "component-path"} is an abbreviation for
 	 *     {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyComponentPathImpl}
 	 * </ul>
+	 * <p>
 	 * By default, the {@code ImplicitNamingStrategy} registered under the key
 	 * {@code "default"} is used. If no strategy is explicitly registered under that key,
 	 * {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl} is used.
@@ -867,6 +870,7 @@ public interface AvailableSettings {
 	 *     <li>{@code "legacy"} is an abbreviation for
 	 *     {@link org.hibernate.boot.model.relational.ColumnOrderingStrategyLegacy}
 	 * </ul>
+	 * <p>
 	 * By default, the {@linkplain org.hibernate.boot.model.relational.ColumnOrderingStrategy} registered under the key
 	 * {@code "default"} is used. If no strategy is explicitly registered under that key,
 	 * {@link org.hibernate.boot.model.relational.ColumnOrderingStrategyStandard} is used.
@@ -924,7 +928,6 @@ public interface AvailableSettings {
 	 *     <li>the (case insensitive) name of a {@code CollectionClassification} (list e.g.)
 	 *     <li>a {@link Class} representing either {@link java.util.List} or {@link java.util.Collection}
 	 * </ul>
-	 * <p>
 	 *
 	 * @since 6.0
 	 */
@@ -1049,7 +1052,7 @@ public interface AvailableSettings {
 	String BATCH_STRATEGY = "hibernate.jdbc.factory_class";
 
 	/**
-	 * When enabled, specifies that {@link jakarta.persistence.Version versioned}
+	 * When enabled, specifies that {@linkplain jakarta.persistence.Version versioned}
 	 * data should be included in batching.
 	 *
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyJdbcBatchingForVersionedEntities(boolean)
@@ -1069,6 +1072,7 @@ public interface AvailableSettings {
 	 *     <li>an instance of {@link java.time.ZoneId}, or
 	 *     <li>a time zone ID string to be passed to {@link java.time.ZoneId#of(String)}.
 	 * </ul>
+	 * <p>
 	 * By default, the {@linkplain java.util.TimeZone#getDefault() JVM default time zone}
 	 * is assumed by the JDBC driver.
 	 *
@@ -1101,6 +1105,7 @@ public interface AvailableSettings {
 	 *         or
 	 *     <li>the name of one of its instances.
 	 * </ul>
+	 * <p>
 	 * The default is {@code DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION}.
 	 *
 	 * @see org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode
@@ -1367,6 +1372,7 @@ public interface AvailableSettings {
 	 *     <li>a {@link Class} implementing {@link org.hibernate.cache.spi.RegionFactory}, or
 	 *     <li>he name of a class implementing {@link org.hibernate.cache.spi.RegionFactory}.
 	 * </ul>
+	 * <p>
 	 * Defaults to {@link NoCachingRegionFactory}, so that caching is disabled.
 	 *
 	 * @see #USE_SECOND_LEVEL_CACHE
@@ -2053,6 +2059,7 @@ public interface AvailableSettings {
 	 *     <li>a {@link Class} representing a class that implements {@code Interceptor}, or
 	 *     <li>the name of a class that implements {@code Interceptor}.
 	 * </ul>
+	 * <p>
 	 * This setting identifies an {@code Interceptor} which is effectively a singleton
 	 * across all the sessions opened from the {@code SessionFactory} to which it is
 	 * applied; the same instance will be passed to each {@code Session}. If there
@@ -2074,6 +2081,7 @@ public interface AvailableSettings {
 	 *     <li>the name of a class that implements {@code Interceptor}, or
 	 *     <li>an instance of {@link Supplier} used to obtain the interceptor.
 	 * </ul>
+	 * <p>
 	 * Note that this setting cannot specify an {@code Interceptor} instance.
 	 * <p>
 	 * This setting identifies an {@code Interceptor} implementation that is to be
@@ -2303,6 +2311,7 @@ public interface AvailableSettings {
 	 *         setting requires DEBUG logging be enabled for
 	 *         {@link org.hibernate.event.internal.EntityCopyAllowedLoggedObserver}.
 	 * </ul>
+	 * <p>
 	 * Alternatively, the application may customize the behavior by providing an
 	 * implementation of {@link org.hibernate.event.spi.EntityCopyObserver} and setting
 	 * the property {@value #MERGE_ENTITY_COPY_OBSERVER} to the class name.
@@ -2328,6 +2337,7 @@ public interface AvailableSettings {
 	 *     <li>The {@link org.hibernate.query.criteria.ValueHandlingMode#INLINE "inline"}
 	 *     mode inlines values as SQL literals.
 	 * </ul>
+	 * <p>
 	 * The default value is {@link org.hibernate.query.criteria.ValueHandlingMode#BIND}.
 	 *
 	 * @since 6.0.0
@@ -2580,6 +2590,7 @@ public interface AvailableSettings {
 	 *     <li>{@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode#EXCEPTION "exception"}
 	 *     specifies that a {@link org.hibernate.HibernateException} should be thrown.
 	 * </ul>
+	 * <p>
 	 * By default, a warning is logged.
 	 *
 	 * @since 5.2.17
@@ -2705,6 +2716,7 @@ public interface AvailableSettings {
 	 *     <li>the name of a class that implements {@code FormatMapper}, or
 	 *     <li>one of the shorthand constants {@code jackson} or {@code jsonb}.
 	 * </ul>
+	 * <p>
 	 * By default, the first of the possible providers that is available at runtime is
 	 * used, according to the listing order.
 	 *
@@ -2721,6 +2733,7 @@ public interface AvailableSettings {
 	 *     <li>the name of a class that implements {@code FormatMapper}, or
 	 *     <li>one of the shorthand constants {@code jackson} or {@code jaxb}.
 	 * </ul>
+	 * <p>
 	 * By default, the first of the possible providers that is available at runtime is
 	 * used, according to the listing order.
 	 *

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

@@ -72,11 +72,12 @@ import jakarta.persistence.SharedCacheMode;
  * <li>entity O/R mappings, defined in either {@linkplain #addAnnotatedClass
  *    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.
  * <p>
  * Configuration properties are enumerated by {@link AvailableSettings}.
- * <pre>{@code
+ * <pre>
  *  SessionFactory factory = new Configuration()
  *     // scan classes for mapping annotations
  *     .addAnnotatedClass(Item.class)
@@ -88,7 +89,8 @@ import jakarta.persistence.SharedCacheMode;
  *     .setProperty(AvailableSettings.DATASOURCE,
  *                  "java:comp/env/jdbc/test")
  *     .getSessionFactory();
- * }</pre>
+ * </pre>
+ * <p>
  * In addition, there are convenience methods for adding
  * {@link #addAttributeConverter attribute converters},
  * {@link #registerTypeContributor type contributors},

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

@@ -34,6 +34,7 @@ import static org.hibernate.internal.log.DeprecationLogger.DEPRECATION_LOGGER;
  * <li><em>System-level</em> properties are shared by all factory instances and are
  * always determined by the {@code Environment} properties in {@link #getProperties()}.
  * </ul>
+ * <p>
  * The only system-level properties are {@value #USE_REFLECTION_OPTIMIZER} and
  * {@value #BYTECODE_PROVIDER}.
  * <p>

hibernate-core/src/main/java/org/hibernate/context/internal/ManagedSessionContext.java

@@ -33,9 +33,10 @@ import org.hibernate.engine.spi.SessionFactoryImplementor;
  * current session it is scoping.  This portion is static to allow easy
  * reference from that external thing.
  * </ul>
+ * <p>
  * The underlying storage of the current sessions here is a static
  * {@link ThreadLocal}-based map where the sessions are keyed by the
- * the owning session factory.
+ * owning session factory.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/dialect/DerbyDialect.java

@@ -867,7 +867,7 @@ public class DerbyDialect extends Dialect {
 	 * <pre>
 	 *     The DECLARE GLOBAL TEMPORARY TABLE statement defines a temporary table for the current connection.
 	 * </pre>
-	 *
+	 * <p>
 	 * {@link DB2Dialect} returns a {@link GlobalTemporaryTableMutationStrategy} that
 	 * will make temporary tables created at startup and hence unavailable for subsequent connections.<br/>
 	 * see HHH-10238.

hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java

@@ -254,6 +254,7 @@ import static org.hibernate.type.descriptor.DateTimeUtils.appendAsTimestampWithN
  *     mappings for standard HQL functions with the
  *     {@link org.hibernate.query.sqm.function.SqmFunctionRegistry}.
  * </ul>
+ * <p>
  * A subclass representing a dialect of SQL which deviates significantly
  * from ANSI SQL will certainly override many additional operations.
  * <p>
@@ -4410,6 +4411,7 @@ public abstract class Dialect implements ConversionContext {
 	 *     <li>s: seconds</li>
 	 *     <li>z,Z,x: timezone offset</li>
 	 * </ul>
+	 * <p>
 	 * In addition, punctuation characters and
 	 * single-quoted literal strings are accepted.
 	 * <p>

hibernate-core/src/main/java/org/hibernate/dialect/TypeNames.java

@@ -25,36 +25,32 @@ import java.util.TreeMap;
  * unmarked default type otherwise.
  * <p>
  * For example, setting:
- *
  * <pre>
  *	names.put( type,        "TEXT" );
  *	names.put( type,   255, "VARCHAR($l)" );
  *	names.put( type, 65534, "LONGVARCHAR($l)" );
  * </pre>
- *
+ * <p>
  * will give you back the following:
- *
  * <pre>
  *  names.get( type )         // --> "TEXT" (default)
  *  names.get( type,    100 ) // --> "VARCHAR(100)" (100 is in [0:255])
  *  names.get( type,   1000 ) // --> "LONGVARCHAR(1000)" (1000 is in [256:65534])
  *  names.get( type, 100000 ) // --> "TEXT" (default)
  * </pre>
- *
+ * <p>
  * On the other hand, simply putting:
- *
  * <pre>
  *	names.put( type, "VARCHAR($l)" );
  * </pre>
- *
+ * <p>
  * would result in:
- *
  * <pre>
  *  names.get( type )        // --> "VARCHAR($l)" (will cause trouble)
  *  names.get( type, 100 )   // --> "VARCHAR(100)"
  *  names.get( type, 10000 ) // --> "VARCHAR(10000)"
  * </pre>
- *
+ * <p>
  * Registered type names may contain the placemarkers {@code $l}, {@code $p},
  * and {@code $s}, which will be replaced by the length, precision, and size
  * passed to {@link #get(int, Long, Integer, Integer)}.

hibernate-core/src/main/java/org/hibernate/dialect/package-info.java

@@ -17,6 +17,7 @@
  *     in this package in order to customize certain aspects of
  *     the SQL generated by Hibernate.
  * </ul>
+ * <p>
  * A concrete {@code Dialect} may be explicitly selected using
  * {@value org.hibernate.cfg.AvailableSettings#DIALECT}, but
  * this is not usually necessary unless a program uses a custom

hibernate-core/src/main/java/org/hibernate/dialect/pagination/SQLServer2005LimitHandler.java

@@ -69,7 +69,7 @@ public class SQLServer2005LimitHandler extends AbstractLimitHandler {
 	 * select [alias-list] from query_
 	 * where rownumber_ >= ? and rownumber_ < ?
 	 * </pre>
-	 *
+	 * <p>
 	 * Where {@code [original-query]} is the original SQL query, with a
 	 * {@code top()} clause added iff the query has an {@code order by}
 	 * clause, and with generated aliases added to any elements of the

hibernate-core/src/main/java/org/hibernate/dialect/unique/CreateTableUniqueDelegate.java

@@ -24,6 +24,7 @@ import org.hibernate.mapping.UniqueKey;
  * <li>For unique keys with no explicit name, it results in {@code unique(x, y)} after the
  *     column list.
  * </ul>
+ * <p>
  * Counterintuitively, this class extends {@link AlterTableUniqueDelegate}, since it falls back
  * to using {@code alter table} for {@linkplain org.hibernate.tool.schema.spi.SchemaMigrator
  * schema migration}.

hibernate-core/src/main/java/org/hibernate/dialect/unique/UniqueDelegate.java

@@ -65,6 +65,7 @@ public interface UniqueDelegate {
 	 * Get the SQL fragment used to specify the unique constraints on the given table as part of
 	 * the {@code create table} command, with a leading comma, usually something like:
 	 * <pre>{@code , unique(x,y), constraint abc unique(a,b,c)}</pre>
+	 * <p>
 	 * or return an empty string if there are no unique constraints or if the unique constraints
 	 * do not belong in the table definition.
 	 * <p>

hibernate-core/src/main/java/org/hibernate/engine/internal/AbstractEntityEntry.java

@@ -73,6 +73,7 @@ public abstract class AbstractEntityEntry implements Serializable, EntityEntry {
 	 *
 	 * 0000 0000 | 0000 0000 | 0654 3333 | 2222 1111
 	 * </pre>
+	 * <p>
 	 * Use {@link #setCompressedValue(EnumState, Enum)},
 	 * {@link #getCompressedValue(EnumState)} etc
 	 * to access the enums and booleans stored in this value.

hibernate-core/src/main/java/org/hibernate/engine/internal/EntityEntryContext.java

@@ -42,7 +42,6 @@ import static org.hibernate.engine.internal.ManagedTypeHelper.isManagedEntity;
  *         either directly or through bytecode enhancement.
  *     </li>
  * </ul>
- * <p>
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/MutationStatementPreparer.java

@@ -26,10 +26,12 @@ public interface MutationStatementPreparer {
 
 	/**
 	 * Prepare an INSERT statement, specifying how auto-generated (by the database) keys should be handled.  Really this
-	 * is a boolean, but JDBC opted to define it instead using 2 int constants:<ul>
+	 * is a boolean, but JDBC opted to define it instead using 2 int constants:
+	 * <ul>
 	 *     <li>{@link PreparedStatement#RETURN_GENERATED_KEYS}</li>
 	 *     <li>{@link PreparedStatement#NO_GENERATED_KEYS}</li>
 	 * </ul>
+	 * <p>
 	 * Generated keys are accessed afterwards via {@link PreparedStatement#getGeneratedKeys}
 	 *
 	 * @param sql The INSERT SQL

hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/StatementPreparer.java

@@ -46,10 +46,12 @@ public interface StatementPreparer {
 
 	/**
 	 * Prepare an INSERT statement, specifying how auto-generated (by the database) keys should be handled.  Really this
-	 * is a boolean, but JDBC opted to define it instead using 2 int constants:<ul>
+	 * is a boolean, but JDBC opted to define it instead using 2 int constants:
+	 * <ul>
 	 *     <li>{@link PreparedStatement#RETURN_GENERATED_KEYS}</li>
 	 *     <li>{@link PreparedStatement#NO_GENERATED_KEYS}</li>
 	 * </ul>
+	 * <p>
 	 * Generated keys are accessed afterwards via {@link PreparedStatement#getGeneratedKeys}
 	 *
 	 * @param sql The INSERT SQL

hibernate-core/src/main/java/org/hibernate/engine/spi/EntityEntry.java

@@ -115,6 +115,7 @@ public interface EntityEntry {
 	 * <li>the entity is not read-only</li>
 	 * <li>if the current status is Status.DELETED, then the entity was not read-only when it was deleted</li>
 	 * </ul>
+	 * 
 	 * @return true, if the entity is modifiable; false, otherwise,
 	 */
 	boolean isModifiableEntity();

hibernate-core/src/main/java/org/hibernate/engine/spi/LoadQueryInfluencers.java

@@ -22,7 +22,7 @@ import org.hibernate.loader.ast.spi.CascadingFetchProfile;
 
 /**
  * Centralize all options which can influence the SQL query needed to load an
- * entity.  Currently such influencers are defined as:<ul>
+ * entity.  Currently, such influencers are defined as:<ul>
  * <li>filters</li>
  * <li>fetch profiles</li>
  * <li>internal fetch profile (merge profile, etc)</li>

hibernate-core/src/main/java/org/hibernate/engine/spi/SharedSessionContractImplementor.java

@@ -287,6 +287,7 @@ public interface SharedSessionContractImplementor
 	 *     though it might return an existing proxy; if it does not exist, a
 	 *     {@code null} value is returned.
 	 * </ul>
+	 * <p>
 	 * When {@code eager = true}, the object is eagerly fetched from the database.
 	 */
 	Object internalLoad(String entityName, Object id, boolean eager, boolean nullable)

hibernate-core/src/main/java/org/hibernate/event/spi/MergeContext.java

@@ -26,6 +26,7 @@ import org.hibernate.pretty.MessageHelper;
  * <li>A <em>managed entity</em> (the {@code managedEntity} method parameter) is
  *     the managed entity that is the result of merging an entity.
  * </ul>
+ * <p>
  * A merge entity can be transient, detached, or managed. If it is managed, then
  * it is identical to its resulting managed entity.
  * <p>
@@ -53,6 +54,7 @@ import org.hibernate.pretty.MessageHelper;
  * <li>The map returned by {@link #invertMap()} will only contain the "newest"
  *     (most recently added) managed-to-merge cross-reference to its merge entity.
  * </ul>
+ * <p>
  * The following method is intended to be used by an implementation of
  * {@link org.hibernate.event.spi.MergeEventListener} to add a merge entity and its
  * corresponding managed entity to a {@code MergeContext} and indicate if the merge

hibernate-core/src/main/java/org/hibernate/generator/AnnotationBasedGenerator.java

@@ -21,10 +21,11 @@ import java.lang.reflect.Member;
  * <p>
  * For example, implementing {@code AnnotationBasedGenerator<AnnotationType>} is the
  * same as providing a constructor with this signature:
- * <pre>{@code
+ * <pre>
  * public GeneratorClass(AnnotationType config, Member idMember,
  *                      CustomIdGeneratorCreationContext creationContext)
- * }</pre>
+ * </pre>
+ * <p>
  * where {@code GeneratorClass} is the class that implements {@code Generator}, and
  * {@code AnnotationType} is the generator annotation type used to configure the
  * generator.

hibernate-core/src/main/java/org/hibernate/generator/BeforeExecutionGenerator.java

@@ -26,6 +26,7 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
  * <li>the meta-annotation {@link org.hibernate.annotations.IdGeneratorType} or
  * <li>the annotation {@link org.hibernate.annotations.GenericGenerator}.
  * </ul>
+ * <p>
  * On the other hand, generators for regular fields and properties may be integrated using
  * {@link org.hibernate.annotations.ValueGenerationType}, as for any {@link Generator}.
  *

hibernate-core/src/main/java/org/hibernate/generator/Generator.java

@@ -34,6 +34,7 @@ import static org.hibernate.generator.EventType.UPDATE;
  *	   SQL {@code select}, though in certain cases this additional round trip may be avoided.
  *	   An important example is id generation using an identity column.
  * </ul>
+ * <p>
  * Generically, a generator may be integrated with the program using the meta-annotation
  * {@link org.hibernate.annotations.ValueGenerationType}, which associates the generator with
  * a Java annotation type, called the <em>generator annotation</em>. A generator may receive
@@ -45,6 +46,7 @@ import static org.hibernate.generator.EventType.UPDATE;
  * <li>declare a constructor which accepts just the annotation instance, or
  * <li>declare a only default constructor, in which case it will not receive parameters.
  * </ul>
+ * <p>
  * A generator must implement {@link #getEventTypes()} to specify the events for which it should be
  * called to produce a new value. {@link EventTypeSets} provides a convenient list of possibilities.
  * <p>

hibernate-core/src/main/java/org/hibernate/generator/OnExecutionGenerator.java

@@ -107,6 +107,7 @@ public interface OnExecutionGenerator extends Generator {
 	 *     <li>a second unique key of the entity, that is, a property annotated
 	 *         {@link org.hibernate.annotations.NaturalId @NaturalId}.
 	 * </ul>
+	 * <p>
 	 * Alternatively, if the generated id is an identity/"autoincrement" column, we can take
 	 * advantage of special platform-specific functionality to retrieve it. Taking advantage
 	 * of the specialness of identity columns is the job of one particular implementation:

hibernate-core/src/main/java/org/hibernate/generator/internal/VersionGeneration.java

@@ -25,6 +25,7 @@ import static org.hibernate.generator.EventTypeSets.INSERT_AND_UPDATE;
  * <li>{@link org.hibernate.type.descriptor.java.VersionJavaType#seed} to seed an initial version, and
  * <li>{@link org.hibernate.type.descriptor.java.VersionJavaType#next} to increment a version.
  * </ul>
+ * <p>
  * Thus, this implementation reproduces the "classic" behavior of Hibernate. A custom generator specified
  * using a {@linkplain org.hibernate.annotations.ValueGenerationType generator annotation} will override
  * this implementation, allowing customized versioning.

hibernate-core/src/main/java/org/hibernate/id/IdentifierGenerator.java

@@ -50,6 +50,7 @@ import static org.hibernate.generator.EventTypeSets.INSERT_ONLY;
  * <li>{@linkplain org.hibernate.annotations.Parameter parameters} specified
  *     using {@link org.hibernate.annotations.GenericGenerator#parameters()}.
  * </ul>
+ * <p>
  * Instances of {@code IdentifierGenerator} are usually created and configured
  * by the {@link org.hibernate.id.factory.IdentifierGeneratorFactory} service.
  * It is not usually correct to use an {@code IdentifierGenerator} with the

hibernate-core/src/main/java/org/hibernate/id/SelectGenerator.java

@@ -25,39 +25,42 @@ import static org.hibernate.generator.internal.NaturalIdHelper.getNaturalIdPrope
  * <li>the mapped {@linkplain org.hibernate.annotations.NaturalId} of the entity, or
  * <li>a property specified using the parameter named {@code "key"}.
  * </ul>
+ * <p>
  * The second approach is provided for backward compatibility with older versions of
  * Hibernate.
  * <p>
  * This generator is intended for use with primary keys assigned by a database trigger
  * or something similar, for example:
- * <pre>{@code
+ * <pre>
- * @Entity @Table(name="TableWithPKAssignedByTrigger")
+ * &#64;Entity &#64;Table(name="TableWithPKAssignedByTrigger")
- * @GenericGenerator(name = "triggered", type = SelectGenerator.class)
+ * &#64;GenericGenerator(name = "triggered", type = SelectGenerator.class)
  * public class TriggeredEntity {
- *     @Id @GeneratedValue(generator = "triggered")
+ *     &#64;Id @GeneratedValue(generator = "triggered")
  *     private Long id;
  *
- *     @NaturalId
+ *     &#64;NaturalId
  *     private String name;
  *
  *     ...
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * However, after a very long working life, this generator is now handing over its
  * work to {@link org.hibernate.generator.internal.GeneratedGeneration}, and the
  * above code may be written as:
- * <pre>{@code
+ * <pre>
- * @Entity @Table(name="TableWithPKAssignedByTrigger")
+ * &#64;Entity &#64;Table(name="TableWithPKAssignedByTrigger")
  * public class TriggeredEntity {
- *     @Id @Generated
+ *     &#64;Id &#64;Generated
  *     private Long id;
  *
- *     @NaturalId
+ *     &#64;NaturalId
  *     private String name;
  *
  *     ...
  * }
- * }</pre>
+ * </pre>
+ * <p>
  * For tables with identity/autoincrement columns, use {@link IdentityGenerator}.
  * <p>
  * The actual work involved in retrieving the primary key value is the job of

hibernate-core/src/main/java/org/hibernate/id/UUIDGenerationStrategy.java

@@ -27,6 +27,7 @@ public interface UUIDGenerationStrategy extends Serializable {
 	 * <li>4 = random numbers based</li>
 	 * <li>5 = name based (sha-1 hash)</li>
 	 * </ul>
+	 * <p>
 	 * Returning the values above should be reserved to those generators creating variants compliant with the
 	 * corresponding RFC definition; others can feel free to return other values as they see fit.
 	 * <p>

hibernate-core/src/main/java/org/hibernate/id/UUIDGenerator.java

@@ -32,7 +32,7 @@ import org.hibernate.type.descriptor.java.UUIDJavaType;
  * <li>{@link #UUID_GEN_STRATEGY_CLASS} - names the {@link UUIDGenerationStrategy} class to use</li>
  * </ul>
  * <p>
- * Currently there are 2 standard implementations of {@link UUIDGenerationStrategy}:<ul>
+ * Currently, there are 2 standard implementations of {@link UUIDGenerationStrategy}:<ul>
  * <li>{@link StandardRandomStrategy} (the default, if none specified)</li>
  * <li>{@link org.hibernate.id.uuid.CustomVersionOneStrategy}</li>
  * </ul>

hibernate-core/src/main/java/org/hibernate/id/factory/IdentifierGeneratorFactory.java

@@ -35,6 +35,7 @@ import jakarta.persistence.GenerationType;
  *     by the {@code @GenericGenerator} annotation, or
  * <li>a JPA-defined {@link GenerationType}.
  * </ul>
+ * <p>
  * A new generator passed a {@link Properties} object containing parameters via the
  * method {@link IdentifierGenerator#configure(Type, Properties, ServiceRegistry)}.
  * <p>

hibernate-core/src/main/java/org/hibernate/id/insert/InsertGeneratedIdentifierDelegate.java

@@ -30,6 +30,7 @@ import org.hibernate.sql.model.ast.builder.TableInsertBuilder;
  * <li>building the SQL {@code insert} statement, and
  * <li>retrieving the generated identifier value using JDBC.
  * </ul>
+ * <p>
  * The implementation should be written to handle any instance of
  * {@link org.hibernate.generator.OnExecutionGenerator}.
  *

hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java

@@ -142,6 +142,7 @@ import static java.util.Collections.unmodifiableSet;
  * <li> delegates JDBC {@code Connection} management to the {@code ConnectionProvider}
  * <li>factory for instances of {@code SessionImpl}
  * </ul>
+ * <p>
  * This class must appear immutable to clients, even if it does all kinds of caching
  * and pooling under the covers. It is crucial that the class is not only thread
  * safe, but also highly concurrent. Synchronization must be used extremely sparingly.

hibernate-core/src/main/java/org/hibernate/jpa/package-info.java

@@ -17,6 +17,7 @@
  *    default (something Hibernate only does if it has a really good
  *    reason to do so).
  * </ul>
+ * <p>
  * Enumerates the {@linkplain jakarta.persistence.Query#setHint hints}
  * recognized by Hibernate:
  * <ul>