From eb6cb31fdfe8fecbe79da789eff3bd4f3d62bd0f Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Wed, 13 Nov 2024 09:52:51 +0100
Subject: [PATCH] add some javadoc to KeyedResultList, Order, Page

---
 .../org/hibernate/query/KeyedResultList.java  |  4 ++++
 .../main/java/org/hibernate/query/Order.java  | 21 ++++++++++++++++++-
 .../main/java/org/hibernate/query/Page.java   | 18 +++++++++++++---
 3 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/query/KeyedResultList.java b/hibernate-core/src/main/java/org/hibernate/query/KeyedResultList.java
index fac3448058..3f6fc41f5b 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/KeyedResultList.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/KeyedResultList.java
@@ -47,6 +47,10 @@ import java.util.List;
  * }
  * </pre>
  *
+ * @apiNote This class is similar to {@code jakarta.data.page.CursoredPage},
+ *          and is used by Hibernate Data Repositories to implement
+ *          Jakarta Data query methods.
+ *
  * @since 6.5
  *
  * @see KeyedPage
diff --git a/hibernate-core/src/main/java/org/hibernate/query/Order.java b/hibernate-core/src/main/java/org/hibernate/query/Order.java
index be7c6a1b56..a15d241d85 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/Order.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/Order.java
@@ -20,7 +20,22 @@ import static org.hibernate.query.SortDirection.DESCENDING;
  * <p>
  * This is a convenience class which allows query result ordering
  * rules to be passed around the system before being applied to
- * a {@link Query} by calling {@link SelectionQuery#setOrder}.
+ * a {@link Query} by calling {@link SelectionQuery#setOrder(Order)}.
+ * <pre>
+ * session.createSelectionQuery("from Book b join b.authors a where a.name = :name", Book.class)
+ *         .setParameter("name", authorName)
+ *         .setOrder(asc(Book_.publicationDate))
+ *         .getResultList();
+ * </pre>
+ * <p>
+ * {@code Order}s may be stacked using {@link List#of} and
+ * {@link SelectionQuery#setOrder(List)}.
+ * <pre>
+ * session.createSelectionQuery("from Book b join b.authors a where a.name = :name", Book.class)
+ *         .setParameter("name", authorName)
+ *         .setOrder(List.of(asc(Book_.publicationDate), desc(Book_.ssn)))
+ *         .getResultList();
+ * </pre>
  * <p>
  * A parameter of a {@linkplain org.hibernate.annotations.processing.Find
  * finder method} or {@linkplain org.hibernate.annotations.processing.HQL
@@ -30,6 +45,10 @@ import static org.hibernate.query.SortDirection.DESCENDING;
  *
  * @param <X> The result type of the query to be sorted
  *
+ * @apiNote This class is similar to {@code jakarta.data.Sort}, and is
+ *          used by Hibernate Data Repositories to implement Jakarta Data
+ *          query methods.
+ *
  * @see SelectionQuery#setOrder(Order)
  * @see SelectionQuery#setOrder(java.util.List)
  *
diff --git a/hibernate-core/src/main/java/org/hibernate/query/Page.java b/hibernate-core/src/main/java/org/hibernate/query/Page.java
index 5a97b404d0..ff1ff26ff9 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/Page.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/Page.java
@@ -10,11 +10,19 @@ import java.util.List;
 
 /**
  * Identifies a page of query results by {@linkplain #size page size}
- * and {@linkplain #number page number}.
+ * and {@linkplain #number page number}. This is an alternative to the
+ * use of the JPA-defined operations {@link SelectionQuery#setFirstResult}
+ * and {@link SelectionQuery#setMaxResults}.
+ * <pre>
+ * session.createSelectionQuery("from Book b join b.authors a where a.name = :name", Book.class)
+ *         .setParameter("name", authorName)
+ *         .setPage(Page.first(100))
+ *         .getResultList();
+ * </pre>
  * <p>
  * This is a convenience class which allows a reference to a page of
- * results to be passed around the system before being applied to
- * a {@link Query} by calling {@link Query#setPage(Page)}.
+ * 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.Find
  * finder method} or {@linkplain org.hibernate.annotations.processing.HQL
@@ -23,6 +31,10 @@ import java.util.List;
  * For key-based pagination, call {@link #keyedBy(Order)} to obtain a
  * {@link KeyedPage}.
  *
+ * @apiNote This class is similar to {@code jakarta.data.page.PageRequest},
+ *          and is used by Hibernate Data Repositories to implement
+ *          Jakarta Data query methods.
+ *
  * @see SelectionQuery#setPage(Page)
  *
  * @since 6.3