HHH-17779 update Javadoc

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

@@ -149,6 +149,13 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * @Find
  * List<Book> getBooksWithTitle(String title, List<Order<Book>> order);
  * </pre>
+ * <p>
+ * As a further exception, a method might support key-based pagination.
+ * Then it must have:
+ * <ul>
+ * <li>return type {@link org.hibernate.query.KeyedResultList}, and
+ * <li>a parameter of type {@link org.hibernate.query.KeyedPage}.
+ * </ul>
  *
  * @see HQL
  * @see SQL

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

@@ -129,6 +129,13 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * List<Book> findBooksByTitleWithPagination(String title, Page page, Order<Book> order);
  * </pre>
  * <p>
+ * As a further exception, a method might support key-based pagination.
+ * Then it must have:
+ * <ul>
+ * <li>return type {@link org.hibernate.query.KeyedResultList}, and
+ * <li>a parameter of type {@link org.hibernate.query.KeyedPage}.
+ * </ul>
+ * <p>
  * Queries specified using this annotation are always validated by
  * the Metamodel Generator, and so it isn't necessary to specify the
  * {@link CheckHQL} annotation.

hibernate-core/src/main/java/org/hibernate/query/KeyedPage.java

@@ -39,6 +39,11 @@ import static org.hibernate.query.KeyedPage.KeyInterpretation.NO_KEY;
  *         session.createQuery("from Book", Book.class)
  *                .getKeyedResultList(nextPage);
  * </pre>
+ * <p>
+ * A parameter of a {@linkplain org.hibernate.annotations.processing.Find
+ * finder method} or {@linkplain org.hibernate.annotations.processing.HQL
+ * HQL query method} may be declared with type {@code Page}. Then the
+ * return type of the method should be {@link KeyedResultList}.
  *
  * @since 6.5
  *

hibernate-core/src/main/java/org/hibernate/query/Order.java

@@ -21,7 +21,8 @@ import static java.util.stream.Collectors.toList;
  * rules to be passed around the system before being applied to
  * a {@link Query} by calling {@link SelectionQuery#setOrder}.
  * <p>
- * A parameter of a {@linkplain org.hibernate.annotations.processing.HQL
+ * A parameter of a {@linkplain org.hibernate.annotations.processing.Find
+ * finder method} or {@linkplain org.hibernate.annotations.processing.HQL
  * HQL query method} may be declared 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.

hibernate-core/src/main/java/org/hibernate/query/Page.java

@@ -18,7 +18,8 @@ import java.util.List;
  * results to be passed around the system before being applied to
  * a {@link Query} by calling {@link Query#setPage(Page)}.
  * <p>
- * A parameter of a {@linkplain org.hibernate.annotations.processing.HQL
+ * A parameter of a {@linkplain org.hibernate.annotations.processing.Find
+ * finder method} or {@linkplain org.hibernate.annotations.processing.HQL
  * HQL query method} may be declared with type {@code Page}.
  *
  * @see SelectionQuery#setPage(Page)

hibernate-core/src/main/java/org/hibernate/query/package-info.java

@@ -15,6 +15,13 @@
  * {@link org.hibernate.query.QueryProducer}, that is, from any
  * {@link org.hibernate.Session} or {@link org.hibernate.StatelessSession}.
  * <p>
+ * The classes {@link org.hibernate.query.Order}, {@link org.hibernate.query.Page},
+ * {@link org.hibernate.query.KeyedPage}, and {@link org.hibernate.query.KeyedResultList}
+ * define an API for dynamic ordering and key-based pagination. These are
+ * classes are especially useful as parameters of generated
+ * {@link org.hibernate.annotations.processing.Find @Find} and
+ * {@link org.hibernate.annotations.processing.HQL @HQL} methods.
+ * <p>
  * Hibernate's extensions to the JPA criteria query API are defined in the
  * subpackage {@link org.hibernate.query.criteria}, with
  * {@link org.hibernate.query.criteria.HibernateCriteriaBuilder} as the