HHH-18979 make Order/Restriction more prominent in jdoc for SelectionQuery

Author: gavinking

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

@@ -17,14 +17,14 @@
 /**
  * A rule for restricting query results.
  * <p>
- * This allows restrictions to be added to a {@link Query} by calling
+ * This allows restrictions to be added to a {@link SelectionQuery} by calling
  * {@link SelectionQuery#addRestriction(Restriction)}.
  * <pre>
  * session.createSelectionQuery("from Book", Book.class)
  *         .addRestriction(Restriction.like(Book_.title, "%Hibernate%", false))
  *         .addRestriction(Restriction.greaterThan(Book_.pages, 100))
  *         .setOrder(Order.desc(Book_.title))
- * 		   .getResultList() );
+ *         .getResultList() );
  * </pre>
  * <p>
  * Each restriction pairs an {@linkplain SingularAttribute attribute} of the

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

@@ -99,13 +99,25 @@
  * every {@link jakarta.persistence.FetchType#EAGER eager} {@code @ManyToOne} or
  * {@code @OneToOne} association belonging to an entity returned by the query.
  * <p>
+ * The method {@link #addRestriction(Restriction)} allows application of additional
+ * {@linkplain Restriction filtering} to the query results. The static factory
+ * methods of {@code Restriction} are used to express filtering criteria of various
+ * kinds.
+ * <p>
  * Finally, two alternative approaches to pagination are available:
  * <ol>
  * <li>
  * The operations and {@link #setOrder(List)} and {@link #setPage(Page)}, together
  * with {@link Order} and {@link Page}, provide a streamlined API for offset-based
  * pagination, at a slightly higher semantic level than the ancient but dependable
  * {@link #setFirstResult(int)} and {@link #setMaxResults(int)}.
+ * <pre>
+ * session.createSelectionQuery("from Book", Book.class)
+ *         .addRestriction(Restriction.contains(Book_.title, "hibernate", false))
+ *         .setOrder(Order.desc(Book_.title))
+ *         .setPage(Page.first(50))
+ *         .getResultList() );
+ * </pre>
  * <li>
  * On the other hand, {@link KeyedPage} and {@link KeyedResultList}, along with
  * {@link #getKeyedResultList(KeyedPage)}, provide for <em>key-based pagination</em>,