clarify use of Order and Page with @find

[It's allowed!]

Author: gavinking

documentation/src/main/asciidoc/introduction/Generator.adoc

@@ -516,7 +516,7 @@ This lets us declare which associations of `Book` should be pre-fetched by annot
 [[paging-and-ordering]]
 === Paging and ordering
 
-Optionally, a query method may have additional "magic" parameters which do not map to query parameters:
+Optionally, a query method--or a finder method which returns multiple results--may have additional "magic" parameters which do not map to query parameters:
 
 [cols="19,~,32m"]
 |===
@@ -537,7 +537,8 @@ Thus, if we redefine our earlier query method as follows:
 ----
 interface Queries {
     @HQL("from Book where title like :title and type = :type")
-    List<Book> findBooksByTitleAndType(String title, Page page, Order<? super Book>... order);
+    List<Book> findBooksByTitleAndType(String title, Type type,
+                                       Page page, Order<? super Book>... order);
 }
 ----
 
@@ -550,6 +551,19 @@ List<Book> books =
                 Page.page(RESULTS_PER_PAGE, page), Order.asc(Book_.isbn));
 ----
 
+Alternatively, we could have written this query method as a finder method:
+
+[source,java]
+----
+interface Queries {
+    @Find
+    List<Book> getBooksByTitle(String title, Type type,
+                               Page page, Order<? super Book>... order);
+}
+----
+
+This gives some dynamic control over query execution, but what if would like direct control over the `Query` object?
+Well, let's talk about the return type.
 
 [[return-types]]
 === Query and finder method return types

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

@@ -91,7 +91,7 @@
  * or one of the following types:
  * <ul>
  * <li>{@link java.util.List java.util.List&lt;E&gt;},
- * <li>{@code io.smallrye.mutiny.Uni&lt;E&gt;}, when used with Hibernate Reactive,
+ * <li>{@code io.smallrye.mutiny.Uni<E>}, when used with Hibernate Reactive,
  * <li>{@link org.hibernate.query.Query org.hibernate.query.Query&lt;E&gt;},
  * <li>{@link org.hibernate.query.SelectionQuery org.hibernate.query.SelectionQuery&lt;E&gt;},
  * <li>{@link jakarta.persistence.Query jakarta.persistence.Query&lt;E&gt;}, or
@@ -123,7 +123,16 @@
  * <p>
  * As an exception, the method may have at most one parameter of
  * type {@code EntityManager}, {@code Session},
- * {@code StatelessSession}, or {@code Mutiny.Session}.
+ * {@code StatelessSession}, or {@code Mutiny.Session}. Furthermore,
+ * if the finder method returns multiple results, that is, if its
+ * return type is {@code List}, then it may also have:
+ * <ul>
+ * <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>...}
+ *     (varargs) where {@code E} is the entity type returned by the
+ *     query.
+ * </ul>
  *
  * @see HQL
  * @see SQL

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

@@ -545,6 +545,15 @@ private void addFinderMethod(
 					createCriteriaFinder( method, returnType, containerType, entity );
 				}
 				else {
+					for ( VariableElement parameter : method.getParameters() ) {
+						final String type = parameter.asType().toString();
+						if ( isPageParam(type) ) {
+							context.message( parameter, "pagination would have no effect", Diagnostic.Kind.ERROR);
+						}
+						else if ( isOrderParam(type) ) {
+							context.message( parameter, "ordering would have no effect", Diagnostic.Kind.ERROR);
+						}
+					}
 					final long parameterCount =
 							method.getParameters().stream()
 									.filter(AnnotationMetaEntity::isFinderParameterMappingToAttribute)
@@ -570,8 +579,8 @@ private void addFinderMethod(
 	private void createCriteriaFinder(
 			ExecutableElement method, TypeMirror returnType, @Nullable TypeElement containerType, TypeElement entity) {
 		final String methodName = method.getSimpleName().toString();
-		final List<String> paramNames = parameterNames(method);
-		final List<String> paramTypes = parameterTypes(method);
+		final List<String> paramNames = parameterNames( method );
+		final List<String> paramTypes = parameterTypes( method );
 		final String[] sessionType = sessionTypeFromParameters( paramNames, paramTypes );
 		final String methodKey = methodName + paramTypes;
 		for ( VariableElement param : method.getParameters() ) {
@@ -683,8 +692,8 @@ private void createSingleParameterFinder(ExecutableElement method, TypeMirror re
 				method.getParameters().stream()
 						.filter(AnnotationMetaEntity::isFinderParameterMappingToAttribute)
 						.findFirst().orElseThrow();
-		final List<String> paramNames = parameterNames(method);
-		final List<String> paramTypes = parameterTypes(method);
+		final List<String> paramNames = parameterNames( method );
+		final List<String> paramTypes = parameterTypes( method );
 		final String[] sessionType = sessionTypeFromParameters( paramNames, paramTypes );
 		final FieldType fieldType = validateFinderParameter( entity, parameter );
 		if ( fieldType != null ) {