update javadoc for InsertGeneratedIdentifierDelegate

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

@@ -18,17 +18,29 @@ import org.hibernate.metamodel.mapping.BasicEntityIdentifierMapping;
 import org.hibernate.sql.model.ast.builder.TableInsertBuilder;
 
 /**
- * Responsible for handling delegation relating to variants in how
- * insert-generated-identifier generator strategies dictate processing:<ul>
- * <li>building the sql insert statement
- * <li>determination of the generated identifier value
+ * Each implementation defines a strategy for retrieving a primary key
+ * {@linkplain org.hibernate.tuple.InDatabaseGenerator generated by
+ * the database} from the database after execution of an {@code insert}
+ * statement. The generated primary key is usually an {@code IDENTITY}
+ * column, but in principle it might be something else, for example,
+ * a value generated by a trigger.
+ * <p>
+ * An implementation controls:
+ * <ul>
+ * <li>building the SQL {@code insert} statement, and
+ * <li>retrieving the generated identifier value using JDBC.
  * </ul>
+ * The implementation should be written to handle any instance of
+ * {@link org.hibernate.tuple.InDatabaseGenerator}.
+ *
+ * @see org.hibernate.tuple.InDatabaseGenerator
  *
  * @author Steve Ebersole
  */
 public interface InsertGeneratedIdentifierDelegate {
 	/**
-	 * Create a TableInsertBuilder with any specific identity handling encoded
+	 * Create a {@link TableInsertBuilder} with any specific identity
+	 * handling already built in.
 	 */
 	TableInsertBuilder createTableInsertBuilder(
 			BasicEntityIdentifierMapping identifierMapping,
@@ -38,7 +50,8 @@ public interface InsertGeneratedIdentifierDelegate {
 	PreparedStatement prepareStatement(String insertSql, SharedSessionContractImplementor session);
 
 	/**
-	 * Perform the insert and extract the database-generated value
+	 * Perform the {@code insert} and extract the database-generated
+	 * primary key value.
 	 *
 	 * @see #createTableInsertBuilder
 	 */
@@ -49,11 +62,11 @@ public interface InsertGeneratedIdentifierDelegate {
 			SharedSessionContractImplementor session);
 
 	/**
-	 * Build a {@link org.hibernate.sql.Insert} specific to the delegate's mode
-	 * of handling generated key values.
+	 * Build an {@linkplain org.hibernate.sql.Insert insert statement}
+	 * specific to the delegate's mode of handling generated key values.
 	 *
 	 * @param context A context to help generate SQL strings
-	 * @return The insert object.
+	 * @return An {@link IdentifierGeneratingInsert}
 	 *
 	 * @deprecated this is no longer called
 	 */
@@ -61,25 +74,24 @@ public interface InsertGeneratedIdentifierDelegate {
 	IdentifierGeneratingInsert prepareIdentifierGeneratingInsert(SqlStringGenerationContext context);
 
 	/**
-	 * Append SQL specific to the delegate's mode
-	 * of handling generated key values.
+	 * Append SQL specific to this delegate's mode of handling generated
+	 * primary key values to the given {@code insert} statement.
 	 *
-	 * @return The insert SQL.
+	 * @return The processed {@code insert} statement string
 	 */
 	default String prepareIdentifierGeneratingInsert(String insertSQL) {
 		return insertSQL;
 	}
 
 	/**
-	 * Perform the indicated insert SQL statement and determine the identifier value
-	 * generated.
+	 * Execute the given {@code insert} statement and return the generated
+	 * key value.
 	 *
-	 *
-	 * @param insertSQL The INSERT statement string
+	 * @param insertSQL The {@code insert} statement string
 	 * @param session The session in which we are operating
-	 * @param binder The param binder
+	 * @param binder The parameter binder
 	 * 
-	 * @return The generated identifier value.
+	 * @return The generated identifier value
 	 */
 	Object performInsert(String insertSQL, SharedSessionContractImplementor session, Binder binder);