update jdoc of @Find, @HQL, @SQL

hibernate-core/src/main/java/org/hibernate/annotations/processing/Find.java

@@ -113,6 +113,10 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  *     {@linkplain jakarta.persistence.criteria.CriteriaBuilder criteria
  *     query}.
  * </ul>
+ * <p>
+ * As an exception, the method may have at most one parameter of
+ * type {@code EntityManager}, {@code Session},
+ * {@code StatelessSession}, or {@code Mutiny.Session}.
  *
  * @see HQL
  * @see SQL

hibernate-core/src/main/java/org/hibernate/annotations/processing/HQL.java

@@ -49,8 +49,9 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * Alternatively, the type to which the annotated method belongs may
  * also declare an abstract method with no parameters which returns
  * one of the types {@link jakarta.persistence.EntityManager},
- * {@link org.hibernate.StatelessSession},
+ * {@link org.hibernate.Session},
- * or {@link org.hibernate.Session}, for example:
+ * {@link org.hibernate.StatelessSession}, or {@code Mutiny.Session},
+ * for example:
  * <pre>
  * EntityManager entityManager();
  * </pre>
@@ -74,7 +75,8 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * <p>
  * This is reminiscent of traditional DAO-style repositories.
  * <p>
- * The return type of an annotated method must be:
+ * For a {@code select} query, the return type of an annotated method
+ * must be:
  * <ul>
  * <li>an entity type,
  * <li>{@link java.util.List},
@@ -84,6 +86,10 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * <li>{@link jakarta.persistence.TypedQuery}.
  * </ul>
  * <p>
+ * For an {@code insert}, {@code update}, or {@code delete} query,
+ * the return type of the annotated method must be {@code int} or
+ * {@code void}.
+ * <p>
  * The method parameters must match the parameters of the HQL query,
  * either by name or by position:
  * <ul>
@@ -95,6 +101,8 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * <p>
  * As an exception, the method may have:
  * <ul>
+ * <li>a parameter of type {@code EntityManager}, {@code Session},
+ *     {@code StatelessSession}, or {@code Mutiny.Session},
  * <li>a parameter with type {@code Page}, and/or
  * <li>a parameter with type {@code Order<? super E>},
  *     {@code List<Order<? super E>>}, or {@code Order<? super E>...}

hibernate-core/src/main/java/org/hibernate/annotations/processing/SQL.java

@@ -49,8 +49,9 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * Alternatively, the type to which the annotated method belongs may
  * also declare an abstract method with no parameters which returns
  * one of the types {@link jakarta.persistence.EntityManager},
- * {@link org.hibernate.StatelessSession},
+ * {@link org.hibernate.Session},
- * or {@link org.hibernate.Session}, for example:
+ * {@link org.hibernate.StatelessSession}, or {@code Mutiny.Session},
+ * for example:
  * <pre>
  * EntityManager entityManager();
  * </pre>
@@ -91,6 +92,10 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * <li>a named query parameter of form {@code :name} is matched to
  *     the method parameter {@code name}.
  * </ul>
+ * <p>
+ * As an exception, the method may have at most one parameter of
+ * type {@code EntityManager}, {@code Session},
+ * {@code StatelessSession}, or {@code Mutiny.Session}.
  *
  * @see HQL
  * @see Find