improve javadoc for first/max results and rename a parameter

Author: gavinking

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

@@ -624,7 +624,7 @@ interface FetchReturn extends ResultNode {
 	NativeQuery<T> addQueryHint(String hint);
 
 	@Override
-	NativeQuery<T> setMaxResults(int maxResult);
+	NativeQuery<T> setMaxResults(int maxResults);
 
 	@Override
 	NativeQuery<T> setFirstResult(int startPosition);

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

@@ -897,7 +897,7 @@ default Query<R> applyLoadGraph(@SuppressWarnings("rawtypes") RootGraph graph) {
 	// covariant overrides - jakarta.persistence.Query/TypedQuery
 
 	@Override
-	Query<R> setMaxResults(int maxResult);
+	Query<R> setMaxResults(int maxResults);
 
 	@Override
 	Query<R> setFirstResult(int startPosition);

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

@@ -416,25 +416,34 @@ default Stream<R> stream() {
 	SelectionQuery<R> setReadOnly(boolean readOnly);
 
 	/**
-	 * The max number of rows requested for the query results
+	 * The maximum number of query result rows to return.
+	 *
+	 * @return the maximum length of the query result list
 	 */
 	int getMaxResults();
 
 	/**
-	 * Set the max number of rows requested for the query results. Applied
-	 * to the SQL query
+	 * Set the maximum number of query result rows to return.
+	 *
+	 * @param maxResults the maximum length of the query result list
 	 */
-	SelectionQuery<R> setMaxResults(int maxResult);
+	SelectionQuery<R> setMaxResults(int maxResults);
 
 	/**
-	 * The first row position to return from the query results. Applied
-	 * to the SQL query.
+	 * The first query result row to return. The very first row
+	 * of the query result list is considered the zeroth row.
+	 *
+	 * @return the position of the first row to return,
+	 *         indexed from zero
 	 */
 	int getFirstResult();
 
 	/**
-	 * Set the first row position to return from the query results. Applied
-	 * to the SQL query.
+	 * Set the first query result row to return. The very first
+	 * row of the query result list is considered the zeroth row.
+	 *
+	 * @param startPosition the position of the first row to return,
+	 *                      indexed from zero
 	 */
 	SelectionQuery<R> setFirstResult(int startPosition);
 

hibernate-core/src/main/java/org/hibernate/query/hql/spi/SqmQueryImplementor.java

@@ -110,7 +110,7 @@ default <T> SqmQueryImplementor<T> setResultTransformer(ResultTransformer<T> tra
 	SqmQueryImplementor<R> setQueryFlushMode(QueryFlushMode queryFlushMode);
 
 	@Override
-	SqmQueryImplementor<R> setMaxResults(int maxResult);
+	SqmQueryImplementor<R> setMaxResults(int maxResults);
 
 	@Override
 	SqmQueryImplementor<R> setFirstResult(int startPosition);

hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java

@@ -158,8 +158,8 @@ public int getMaxResults() {
 	}
 
 	@Override
-	public QueryImplementor<R> setMaxResults(int maxResult) {
-		super.setMaxResults( maxResult );
+	public QueryImplementor<R> setMaxResults(int maxResults) {
+		super.setMaxResults( maxResults );
 		return this;
 	}
 

hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java

@@ -350,12 +350,12 @@ public SelectionQuery<R> setFlushMode(FlushModeType flushMode) {
 	}
 
 	@Override
-	public SelectionQuery<R> setMaxResults(int maxResult) {
-		if ( maxResult < 0 ) {
+	public SelectionQuery<R> setMaxResults(int maxResults) {
+		if ( maxResults < 0 ) {
 			throw new IllegalArgumentException( "Max results cannot be negative" );
 		}
 		getSession().checkOpen();
-		getQueryOptions().getLimit().setMaxRows(maxResult);
+		getQueryOptions().getLimit().setMaxRows( maxResults );
 		return this;
 	}
 

hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java

@@ -1642,8 +1642,8 @@ public <S> NativeQueryImplementor<S> setResultTransformer(ResultTransformer<S> t
 	}
 
 	@Override
-	public NativeQueryImplementor<R> setMaxResults(int maxResult) {
-		super.setMaxResults( maxResult );
+	public NativeQueryImplementor<R> setMaxResults(int maxResults) {
+		super.setMaxResults( maxResults );
 		return this;
 	}
 

hibernate-core/src/main/java/org/hibernate/query/sql/spi/NativeQueryImplementor.java

@@ -190,7 +190,7 @@ NativeQueryImplementor<R> addJoin(
 	NativeQueryImplementor<R> setComment(String comment);
 
 	@Override
-	NativeQueryImplementor<R> setMaxResults(int maxResult);
+	NativeQueryImplementor<R> setMaxResults(int maxResults);
 
 	@Override
 	NativeQueryImplementor<R> setFirstResult(int startPosition);

hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java

@@ -700,8 +700,8 @@ public SqmQueryImplementor<R> setResultListTransformer(ResultListTransformer<R>
 	}
 
 	@Override
-	public SqmQueryImplementor<R> setMaxResults(int maxResult) {
-		super.setMaxResults( maxResult );
+	public SqmQueryImplementor<R> setMaxResults(int maxResults) {
+		super.setMaxResults( maxResults );
 		return this;
 	}
 

hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java

@@ -190,8 +190,8 @@ public int getMaxResults() {
 	}
 
 	@Override
-	public SqmSelectionQueryImplementor<R> setMaxResults(int maxResult) {
-		getDelegate().setMaxResults( maxResult );
+	public SqmSelectionQueryImplementor<R> setMaxResults(int maxResults) {
+		getDelegate().setMaxResults( maxResults );
 		return this;
 	}