improved explanations of constructor stuff for repositories

Author: gavinking

tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AnnotationMetaEntity.java

@@ -936,13 +936,12 @@ void addEventBus() {
 
 	/**
 	 * For usage with CDI, but outside Quarkus, Jakarta Data
-	 * repositories use {@code @PersistenceUnit} to obtain an
-	 * {@code EntityManagerFactory} via field injection. So in
-	 * that case we will need a {@link DefaultConstructor default
-	 * constructor}. We don't do this in Quarkus, because there
-	 * we can just inject the {@code StatelessSession} directly,
-	 * and so in Quarkus we don't need the default constructor
-	 * at all.
+	 * repositories use {@code @PersistenceUnit} to obtain
+	 * an {@code EntityManagerFactory} via field injection.
+	 * So here we need a {@linkplain DefaultConstructor
+	 * default constructor}. We don't need one in Quarkus,
+	 * because in Quarkus we can inject a container-managed
+	 * {@code StatelessSession} directly.
 	 */
 	boolean needsDefaultConstructor() {
 		return jakartaDataRepository

tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/DefaultConstructor.java

@@ -21,6 +21,13 @@
 
 /**
  * Used by the container to instantiate a Jakarta Data repository.
+ * This is a constructor with no parameters, used to instantiate
+ * a repository which then uses field injection to obtain its
+ * dependencies. By contrast, a {@link RepositoryConstructor} has
+ * a parameter which accepts the session as an argument, allowing
+ * direct instantiation or constructor injection. This class is
+ * only needed because {@code @PersistenceUnit} is incompatible
+ * with CDI-style constructor injection.
  *
  * @author Gavin King
  */

tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/RepositoryConstructor.java

@@ -14,7 +14,11 @@
 import static org.hibernate.processor.util.Constants.NONNULL;
 
 /**
- * A general purpose constructor which accepts the session.
+ * A general purpose constructor which accepts the session as an
+ * argument. This constructor is compatible with use via direct
+ * instantiation or CDI-style constructor injection. By contrast,
+ * {@link DefaultConstructor} is used to instantiate a repository
+ * which obtains its session using field injection.
  *
  * @author Gavin King
  */