add some javadoc to KeyedResultList, Order, Page

Author: gavinking

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

@@ -47,6 +47,10 @@
  * }
  * </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

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

@@ -20,7 +20,22 @@
  * <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 @@
  *
  * @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)
  *

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

@@ -10,11 +10,19 @@
 
 /**
  * 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 @@
  * 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