fix some warnings and wrong info in the javadoc

and slightly improve some jdoc in Dialect
also deprecate an unused method with incorrect jdoc

Author: gavinking

hibernate-core/src/main/java/org/hibernate/boot/archive/scan/package-info.java

@@ -6,10 +6,13 @@
  */
 
 /**
- * Support for scanning {@linkplain org.hibernate.boot.archive.spi.ArchiveDescriptor archives}
+ * Support for {@linkplain org.hibernate.boot.archive.scan.spi.Scanner scanning}
+ * {@linkplain org.hibernate.boot.archive.spi.ArchiveDescriptor archives}
  * to discover managed classes and named resources.
  *
+ * @see org.hibernate.boot.archive.scan.spi.Scanner
  * @see org.hibernate.boot.archive.scan.spi.ScanResult
+ * @see org.hibernate.boot.archive.spi.ArchiveDescriptor
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/boot/archive/scan/spi/package-info.java

@@ -6,10 +6,13 @@
  */
 
 /**
- * SPI for scanning {@linkplain org.hibernate.boot.archive.spi.ArchiveDescriptor archives}
+ * SPI for {@linkplain org.hibernate.boot.archive.scan.spi.Scanner scanning}
+ * {@linkplain org.hibernate.boot.archive.spi.ArchiveDescriptor archives}
  * to discover managed classes and named resources.
  *
  * @see org.hibernate.boot.archive.scan.spi.ScanResult
+ * @see org.hibernate.boot.archive.scan.spi.Scanner
+ * @see org.hibernate.boot.archive.spi
  *
  * @author Steve Ebersole
  */

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

@@ -6,8 +6,12 @@
  */
 
 /**
- * Defines an SPI for {@linkplain org.hibernate.boot.archive.scan scanning}
- * of {@linkplain org.hibernate.boot.archive.spi.ArchiveDescriptor archives}
- * for discovery of managed resources.
+ * Defines a model for
+ * {@linkplain org.hibernate.boot.archive.spi.ArchiveDescriptor archives}
+ * which may be {@link org.hibernate.boot.archive.scan.spi scanned}
+ * to discover managed classes and named resources.
+ *
+ * @see org.hibernate.boot.archive.spi.ArchiveDescriptor
+ * @see org.hibernate.boot.archive.scan.spi
  */
 package org.hibernate.boot.archive.spi;

hibernate-core/src/main/java/org/hibernate/boot/model/package-info.java

@@ -9,7 +9,7 @@
  * This package defines the boot-time metamodel, which is an interpretation
  * of the domain model (entity classes, embeddable classes, and attributes)
  * and the mapping of these "domain model parts" to the database. It is
- * {@linkplain org.hibernate.boot.model.process built incrementally} from
+ * {@linkplain org.hibernate.boot.model.process.spi built incrementally} from
  * {@linkplain org.hibernate.annotations annotations} and XML-based mappings.
  * <p>
  * The interfaces {@link org.hibernate.boot.model.TypeContributor} and

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

@@ -7,22 +7,12 @@
 package org.hibernate.boot.model.source.spi;
 
 /**
- * Describes source information about the key of a persistent map.  At high
- * level this is broken down further into 2 categories:<ul>
- *     <li>{@link PluralAttributeMapKeySourceEntityAttribute}</li>
- *     <li>
- *         <ul>
- *             <li>{@link PluralAttributeMapKeySourceBasic}</li>
- *             <li>{@link PluralAttributeMapKeySourceEmbedded}</li>
- *             <li>{@link PluralAttributeMapKeyManyToManySource}</li>
- *         </ul>
- *     </li>
- * </ul>
- * <p>
- * {@link PluralAttributeMapKeySourceEntityAttribute} is only relevant from
- * annotations when using {@link jakarta.persistence.MapKey}.
+ * Describes source information about the key of a persistent map.
  *
  * @author Steve Ebersole
+ *
+ * @see PluralAttributeMapKeyManyToManySource
+ * @see PluralAttributeMapKeyManyToAnySource
  */
 public interface PluralAttributeMapKeySource extends PluralAttributeIndexSource {
 	enum Nature {
@@ -35,14 +25,17 @@ enum Nature {
 	Nature getMapKeyNature();
 
 	/**
-	 * Is this plural attribute index source for an attribute of the referenced entity
-	 * (relevant only for one-to-many and many-to-many associations)?
-	 *
+	 * Is this plural attribute index source for an attribute of the referenced
+	 * entity (relevant only for one-to-many and many-to-many associations)?
+	 * <p>
 	 * If this method returns {@code true}, then this object can safely
-	 * be cast to {@link PluralAttributeMapKeySourceEntityAttribute}.
+	 * be cast to {@link PluralAttributeMapKeyManyToManySource}.
+	 *
+	 * @return true, if this plural attribute index source for an attribute of
+	 *         the referenced entity; false, otherwise.
 	 *
-	 * @return true, if this plural attribute index source for an attribute of the referenced
-	 * entity; false, otherwise.
+	 * @deprecated no longer used, so this should be removed
 	 */
+	@Deprecated(since = "6.4")
 	boolean isReferencedEntityAttribute();
 }

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

@@ -131,7 +131,7 @@ public interface QuerySettings {
 	 * By default, this is set to false, i.e. native queries will be checked for ordinal placeholders.
 	 * <p>
 	 *
-	 * @see SessionFactoryOptions#getIgnoreNativeJdbcParameters()
+	 * @see SessionFactoryOptions#getNativeJdbcParametersIgnored()
 	 */
 	String NATIVE_IGNORE_JDBC_PARAMETERS = "hibernate.query.native.ignore_jdbc_parameters";
 

hibernate-core/src/main/java/org/hibernate/collection/spi/CollectionInitializerProducer.java

@@ -41,7 +41,7 @@ public interface CollectionInitializerProducer {
 	 * @param collectionValueKeyAssembler allows creation of a
 	 *        {@link org.hibernate.sql.results.graph.DomainResult} for
 	 *        either side of the collection foreign key
-	 * @deprecated Use {@link #produceInitializer(NavigablePath, PluralAttributeMapping, FetchParentAccess, LockMode, DomainResult, DomainResult, AssemblerCreationState)} instead
+	 * @deprecated Use {@link #produceInitializer(NavigablePath, PluralAttributeMapping, FetchParentAccess, LockMode, DomainResult, DomainResult, boolean, AssemblerCreationState)} instead
 	 */
 	@Deprecated(forRemoval = true)
 	CollectionInitializer produceInitializer(

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

@@ -4732,27 +4732,36 @@ public int getMaxVarbinaryCapacity() {
 	}
 
 	/**
-	 * The default length for a LOB column, if LOB columns have a length in
-	 * this dialect.
+	 * This is the default length for a generated column of type
+	 * {@link SqlTypes#BLOB BLOB} or {@link SqlTypes#CLOB CLOB}
+	 * mapped to {@link Blob} or {@link Clob}, if LOB columns
+	 * have a length in this dialect.
 	 *
 	 * @return {@value Size#DEFAULT_LOB_LENGTH} by default
 	 *
 	 * @see Length#LOB_DEFAULT
+	 * @see org.hibernate.type.descriptor.java.BlobJavaType
+	 * @see org.hibernate.type.descriptor.java.ClobJavaType
 	 */
 	public long getDefaultLobLength() {
 		return Size.DEFAULT_LOB_LENGTH;
 	}
 
 	/**
-	 * This is the default precision for a generated
-	 * column mapped to a {@link java.math.BigInteger}
-	 * or {@link java.math.BigDecimal}.
+	 * This is the default precision for a generated column of
+	 * exact numeric type {@link SqlTypes#DECIMAL DECIMAL} or
+	 * {@link SqlTypes#NUMERIC NUMERIC} mapped to a
+	 * {@link java.math.BigInteger} or
+	 * {@link java.math.BigDecimal}.
 	 * <p>
 	 * Usually returns the maximum precision of the
 	 * database, except when there is no such maximum
 	 * precision, or the maximum precision is very high.
 	 *
 	 * @return the default precision, in decimal digits
+	 *
+	 * @see org.hibernate.type.descriptor.java.BigDecimalJavaType
+	 * @see org.hibernate.type.descriptor.java.BigIntegerJavaType
 	 */
 	public int getDefaultDecimalPrecision() {
 		//this is the maximum for Oracle, SQL Server,
@@ -4762,14 +4771,20 @@ public int getDefaultDecimalPrecision() {
 	}
 
 	/**
-	 * This is the default precision for a generated
-	 * column mapped to a {@link Timestamp} or
-	 * {@link java.time.LocalDateTime}.
+	 * This is the default precision for a generated column of
+	 * type {@link SqlTypes#TIMESTAMP TIMESTAMP} mapped to a
+	 * {@link Timestamp} or {@link java.time.LocalDateTime}.
 	 * <p>
 	 * Usually 6 (microseconds) or 3 (milliseconds).
 	 *
 	 * @return the default precision, in decimal digits,
 	 *         of the fractional seconds field
+	 *
+	 * @see org.hibernate.type.descriptor.java.JdbcTimestampJavaType
+	 * @see org.hibernate.type.descriptor.java.LocalDateTimeJavaType
+	 * @see org.hibernate.type.descriptor.java.OffsetDateTimeJavaType
+	 * @see org.hibernate.type.descriptor.java.ZonedDateTimeJavaType
+	 * @see org.hibernate.type.descriptor.java.InstantJavaType
 	 */
 	public int getDefaultTimestampPrecision() {
 		//milliseconds or microseconds is the maximum
@@ -4779,6 +4794,23 @@ public int getDefaultTimestampPrecision() {
 		return 6; //microseconds!
 	}
 
+	/**
+	 * This is the default scale for a generated column of type
+	 * {@link SqlTypes#INTERVAL_SECOND INTERVAL SECOND} mapped
+	 * to a {@link Duration}.
+	 * <p>
+	 * Usually 9 (nanoseconds) or 6 (microseconds).
+	 *
+	 * @return the default scale, in decimal digits,
+	 *         of the fractional seconds field
+	 *
+	 * @see org.hibernate.type.descriptor.java.DurationJavaType
+	 */
+	public int getDefaultIntervalSecondScale(){
+		// The default scale necessary is 9 i.e. nanosecond resolution
+		return 9;
+	}
+
 	/**
 	 * Does this dialect round a temporal when converting from a precision higher to a lower one?
 	 *
@@ -5477,16 +5509,4 @@ public FunctionalDependencyAnalysisSupport getFunctionalDependencyAnalysisSuppor
 		return FunctionalDependencyAnalysisSupportImpl.NONE;
 	}
 
-	/**
-	 * Resolves the default scale for a {@link SqlTypes.INTERVAL_SECOND} type code for the given column
-	 * <p>
-	 * Usually 9 (nanosecond) or 6 (microseconds).
-	 *
-	 * @return the default scale, in decimal digits,
-	 *         of the fractional seconds field
-	 */
-	public int getDefaultIntervalSecondScale(){
-		// The default scale necessary is 9 i.e. nanosecond resolution
-		return 9;
-	}
 }

hibernate-core/src/main/java/org/hibernate/dialect/function/SqlServerConvertTruncFunction.java

@@ -20,7 +20,8 @@
 import org.hibernate.type.spi.TypeConfiguration;
 
 /**
- * Custom {@link TruncFunction} for SQL Server versions < 16 which uses the custom {@link DateTruncConvertEmulation}
+ * Custom {@link TruncFunction} for SQL Server versions before 16,
+ * which uses the custom {@link DateTruncConvertEmulation}
  *
  * @author Marco Belladelli
  */

hibernate-core/src/main/java/org/hibernate/dialect/identity/IdentityColumnSupport.java

@@ -132,7 +132,7 @@ default boolean hasIdentityInsertKeyword() {
 	 *
 	 * @return the dialect specific GetGeneratedKeys delegate
 	 *
-	 * @deprecated Use {@link #buildGetGeneratedKeysDelegate(EntityPersister, Dialect)} instead.
+	 * @deprecated Use {@link #buildGetGeneratedKeysDelegate(EntityPersister)} instead.
 	 */
 	@Deprecated( forRemoval = true, since = "6.5" )
 	default GetGeneratedKeysDelegate buildGetGeneratedKeysDelegate(
@@ -142,12 +142,12 @@ default GetGeneratedKeysDelegate buildGetGeneratedKeysDelegate(
 	}
 
 	/**
-	 * The Delegate for dealing with IDENTITY columns using JDBC3 getGeneratedKeys
+	 * The delegate for dealing with {@code IDENTITY} columns using
+	 * {@link java.sql.PreparedStatement#getGeneratedKeys}.
 	 *
 	 * @param persister The persister
-	 * @param dialect The dialect against which to generate the delegate
 	 *
-	 * @return the dialect specific GetGeneratedKeys delegate
+	 * @return the dialect-specific {@link GetGeneratedKeysDelegate}
 	 */
 	GetGeneratedKeysDelegate buildGetGeneratedKeysDelegate(EntityPersister persister);
 }

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/package-info.java

@@ -6,12 +6,13 @@
  */
 
 /**
- * Package defining support for executing mutation SQL statements produced
- * by the {@linkplain org.hibernate.persister persister} for an entity or
- * collection.
+ * Package defining support for executing mutation SQL statements produced by an
+ * {@linkplain org.hibernate.persister.entity.EntityPersister entity persister} or
+ * {@linkplain org.hibernate.persister.collection.CollectionPersister collection
+ * persister}.
  * <p>
- * The {@link org.hibernate.engine.jdbc.mutation.MutationExecutor} is
- * usually called by the various SQL insert, update, and delete
+ * The {@link org.hibernate.engine.jdbc.mutation.MutationExecutor} is usually
+ * called by the various SQL insert, update, and delete
  * {@linkplain org.hibernate.persister.entity.mutation.AbstractMutationCoordinator
  * coordinators} defined in {@link org.hibernate.persister.entity.mutation}
  * and {@link org.hibernate.persister.collection.mutation}.

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

@@ -26,9 +26,6 @@ public interface ResultSetReturn {
 
 	/**
 	 * Extract the {@link ResultSet} from the {@link PreparedStatement}.
-	 * <p>
-	 * If client passes {@link CallableStatement} reference, this method calls {@link #extract(CallableStatement)}
-	 * internally.  Otherwise, {@link PreparedStatement#executeQuery()} is called.
 	 *
 	 * @param statement The {@link PreparedStatement} from which to extract the {@link ResultSet}
 	 *

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

@@ -51,8 +51,9 @@
  *     </li>
  * </ul>
  *
- * See also {@link org.hibernate.event.spi.EventSource} which extends this interface
- * provides a bridge to the event generation features of {@link org.hibernate.event}.
+ * See also {@link org.hibernate.event.spi.EventSource} which extends this interface,
+ * providing a bridge to the event generation features of {@link org.hibernate.event.spi
+ * org.hibernate.event}.
  *
  * @author Gavin King
  * @author Steve Ebersole

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

@@ -34,8 +34,9 @@
  *     {@linkplain org.hibernate.jpa.boot.spi.Bootstrap bootstrap} the JPA
  *     provider, and interfaces which may be implemented to contribute extensions
  *     during of the bootstrap process.
- * <li>The package {@link org.hibernate.jpa.event} implements support for JPA
- *     {@linkplain jakarta.persistence.EntityListeners event listeners}.
+ * <li>The package {@link org.hibernate.jpa.event.spi org.hibernate.jpa.event}
+ *     implements support for JPA {@linkplain jakarta.persistence.EntityListeners
+ *     event listeners}.
  * <li>The package {@link org.hibernate.jpa.spi} provides SPIs for managing cases
  *     where Hibernate intentionally violates the JPA specification by default
  *     (something Hibernate only does when it has a really good reason to do so).

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

@@ -12,6 +12,6 @@
  * They are not part of the public API of Hibernate, and are not meant to
  * be used directly by typical programs which use Hibernate for persistence.
  *
- * @see org.hibernate.collection
+ * @see org.hibernate.collection.spi
  */
 package org.hibernate.proxy;

hibernate-core/src/main/java/org/hibernate/query/sqm/mutation/spi/SqmMultiTableInsertStrategy.java

@@ -11,18 +11,17 @@
 import org.hibernate.metamodel.mapping.internal.MappingModelCreationProcess;
 import org.hibernate.query.spi.DomainQueryExecutionContext;
 import org.hibernate.query.sqm.internal.DomainParameterXref;
-import org.hibernate.query.sqm.mutation.internal.SqmMutationStrategyHelper;
 import org.hibernate.query.sqm.tree.insert.SqmInsertStatement;
 
 /**
  * Pluggable strategy for defining how insertion (`INSERT`) queries should be handled when the target
  * entity is mapped to multiple tables via secondary tables or certain inheritance strategies or uses an
  * identifier generator that uses an optimizer.
- *
+ * <p>
  * {@link #prepare} and {@link #release} allow the strategy to perform any one time preparation and cleanup.
  *
- * @apiNote See {@link SqmMutationStrategyHelper#resolveStrategy} for standard resolution of the strategy to use
- * for each hierarchy
+ * @apiNote See {@link SqmMultiTableMutationStrategyProvider#createInsertStrategy} for standard resolution
+ *          of the strategy to use for each hierarchy
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/query/sqm/mutation/spi/SqmMultiTableMutationStrategy.java

@@ -11,7 +11,6 @@
 import org.hibernate.metamodel.mapping.internal.MappingModelCreationProcess;
 import org.hibernate.query.spi.DomainQueryExecutionContext;
 import org.hibernate.query.sqm.internal.DomainParameterXref;
-import org.hibernate.query.sqm.mutation.internal.SqmMutationStrategyHelper;
 import org.hibernate.query.sqm.tree.delete.SqmDeleteStatement;
 import org.hibernate.query.sqm.tree.update.SqmUpdateStatement;
 
@@ -25,8 +24,8 @@
  * The methods {@link #prepare} and {@link #release} allow the strategy to perform any one time
  * preparation and cleanup.
  *
- * @apiNote See {@link SqmMutationStrategyHelper#resolveStrategy} for standard resolution of the
- *          strategy to use for each hierarchy.
+ * @apiNote See {@link SqmMultiTableMutationStrategyProvider#createMutationStrategy} for standard
+ *          resolution of the strategy to use for each hierarchy.
  *
  * @author Steve Ebersole
  */