clarify AnnotationBasedGenerator vs constructor for Generators

this was unclear/misleading in the javadoc, as pointed out by @sebersole

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

@@ -52,6 +52,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * The {@code @CustomSequence} annotation itself implies that {@code id} is
  * a generated value.
  * <p>
+ * An id generator annotation may have members, which are used to configure
+ * the id generator, if either:
+ * <ul>
+ * <li>the id generator implements {@link AnnotationBasedGenerator}, or
+ * <li>the id generator class has a constructor with the same signature as
+ *     {@link AnnotationBasedGenerator#initialize}.
+ * </ul>
  * For a more complete example, see the annotation {@link UuidGenerator} and
  * the corresponding generator class {@link org.hibernate.id.uuid.UuidGenerator}.
  * <p>
@@ -67,15 +74,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface IdGeneratorType {
 	/**
-	 * A class which implements {@link Generator} and has a constructor with
+	 * A class which implements {@link Generator}.
-	 * the signature:
-	 * <pre>{@code
-	 * public GeneratorType(AnnotationType config, Member idMember,
-	 *                      CustomIdGeneratorCreationContext creationContext)
-	 * }</pre>
-	 * where {@code GeneratorType} is the class that implements {@code Generator},
-	 * and {@code AnnotationType} is the annotation type to which this annotation
-	 * was applied.
 	 */
 	Class<? extends Generator> value();
 }

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

@@ -56,9 +56,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     database.
  * </ul>
  * A generator annotation may have members, which are used to configure the
- * generation strategy, when the strategy instance in initialized via
+ * value generator, if either:
- * {@link AnnotationBasedGenerator#initialize}.
+ * <ul>
- * <p>
+ * <li>the value generator implements {@link AnnotationBasedGenerator}, or
+ * <li>the value generator class has a constructor with the same signature as
+ *     {@link AnnotationBasedGenerator#initialize}.
+ * </ul>
  * 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.
@@ -77,11 +80,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface ValueGenerationType {
 	/**
-	 * A class that implements {@link Generator}.
+	 * A class which implements {@link Generator}.
-	 * <p>
-	 * If the generator annotation has members used to configure the
-	 * generation strategy instance, the strategy should implement
-	 * {@link AnnotationBasedGenerator}.
 	 */
 	Class<? extends Generator> generatedBy();
 }

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

@@ -19,6 +19,16 @@ import java.lang.reflect.Member;
  * signature as the {@link #initialize} method. But implementing this interface is
  * slightly more typesafe.
  * <p>
+ * For example, implementing {@code AnnotationBasedGenerator<AnnotationType>} is the
+ * same as providing a constructor with this signature:
+ * <pre>{@code
+ * public GeneratorClass(AnnotationType config, Member idMember,
+ *                      CustomIdGeneratorCreationContext creationContext)
+ * }</pre>
+ * where {@code GeneratorClass} is the class that implements {@code Generator}, and
+ * {@code AnnotationType} is the generator annotation type used to configure the
+ * generator.
+ * <p>
  * Every instance of this class must implement either {@link InMemoryGenerator} or
  * {@link InDatabaseGenerator}.
  *