Merged for javadoc

Author: fluentfuture

mug-safesql/src/main/java/com/google/mu/safesql/SafeSql.java

@@ -968,7 +968,8 @@ public <T> Optional<T> queryForOne(
   /**
    * Paginate the encapsulated query by fetching up to {@code pageSize} rows for each page.
    *
-   * <p>If {@code orderByKeys} is non-empty, the column values are used to control pagination.
+   * <p>If {@code orderByKeys} is non-empty, they refer to the columns that must uniquely identify
+   * a row. These column values are then used to control pagination.
    * For example, if {@code [groupId, timestamp]} can uniquely identify a row, the generated
    * SQL will use {@code "groupId" > ? OR ("groupId" = ? AND "timestamp" > ?)} for the next page,
    * comparing against the previous page's last row.
@@ -979,10 +980,11 @@ public <T> Optional<T> queryForOne(
    * 
    * <p>The standard SQL {@code FETCH NEXT ROWS} syntax is used for pagination.
    * If {@code orderByKeys} is empty, the paginated query will use {@code OFFSET} keyword
-   * to specify the next page offset.
+   * instead of the sort key columns to specify the next page offset.
    * 
-   * <p>All column names are automatically double-quoted to avoid clashing with keywords or spaces
-   * in identifiers. If your DB is case sensitive, make sure you pass in the accurate case.
+   * <p>The {@code orderByKeys} column names are automatically double-quoted to avoid clashing
+   * with keywords or spaces in identifiers. 
+   * If your DB is case sensitive, make sure you pass in the accurate case.
    * 
    * <p>The method is lazy. Paginated queries are only sent when the returned stream is consumed.
    * The caller should close the {@code connection} after done, which will close the cached
@@ -1007,7 +1009,8 @@ public <T> Stream<List<T>> paginateLazily(
   /**
    * Paginate the encapsulated query by fetching up to {@code pageSize} rows for each page.
    *
-   * <p>If {@code orderByKeys} is non-empty, the column values are used to control pagination.
+   * <p>If {@code orderByKeys} is non-empty, they refer to the columns that must uniquely identify
+   * a row. These column values are then used to control pagination.
    * For example, if {@code [groupId, timestamp]} can uniquely identify a row, the generated
    * SQL will use {@code "groupId" > ? OR ("groupId" = ? AND "timestamp" > ?)} for the next page,
    * comparing against the previous page's last row.
@@ -1018,10 +1021,11 @@ public <T> Stream<List<T>> paginateLazily(
    * 
    * <p>The standard SQL {@code FETCH NEXT ROWS} syntax is used for pagination.
    * If {@code orderByKeys} is empty, the paginated query will use {@code OFFSET} keyword
-   * to specify the next page offset.
+   * instead of the sort key columns to specify the next page offset.
    * 
-   * <p>All column names are automatically double-quoted to avoid clashing with keywords or spaces
-   * in identifiers. If your DB is case sensitive, make sure you pass in the accurate case.
+   * <p>The {@code orderByKeys} column names are automatically double-quoted to avoid clashing
+   * with keywords or spaces in identifiers. 
+   * If your DB is case sensitive, make sure you pass in the accurate case.
    * 
    * <p>The method is lazy. Paginated queries are only sent when the returned stream is consumed.
    * The caller should close the {@code connection} after done, which will close the cached
@@ -1049,7 +1053,8 @@ public <T> Stream<List<T>> paginateLazily(
   /**
    * Paginate the encapsulated query by fetching up to {@code pageSize} rows for each page.
    *
-   * <p>If {@code orderByKeys} is non-empty, the column values are used to control pagination.
+   * <p>If {@code orderByKeys} is non-empty, they refer to the columns that must uniquely identify
+   * a row. These column values are then used to control pagination.
    * For example, if {@code [groupId, timestamp]} can uniquely identify a row, the generated
    * SQL will use {@code "groupId" > ? OR ("groupId" = ? AND "timestamp" > ?)} for the next page,
    * comparing against the previous page's last row.
@@ -1060,10 +1065,11 @@ public <T> Stream<List<T>> paginateLazily(
    * 
    * <p>The standard SQL {@code FETCH NEXT ROWS} syntax is used for pagination.
    * If {@code orderByKeys} is empty, the paginated query will use {@code OFFSET} keyword
-   * to specify the next page offset.
+   * instead of the sort key columns to specify the next page offset.
    * 
-   * <p>All column names are automatically double-quoted to avoid clashing with keywords or spaces
-   * in identifiers. If your DB is case sensitive, make sure you pass in the accurate case.
+   * <p>The {@code orderByKeys} column names are automatically double-quoted to avoid clashing
+   * with keywords or spaces in identifiers. 
+   * If your DB is case sensitive, make sure you pass in the accurate case.
    * 
    * <p>The method is lazy. Paginated queries are only sent when the returned stream is consumed.
    * The caller should close the {@code connection} after done, which will close the cached
@@ -1088,7 +1094,8 @@ public <T> Stream<List<T>> paginateLazily(
   /**
    * Paginate the encapsulated query by fetching up to {@code pageSize} rows for each page.
    *
-   * <p>If {@code orderByKeys} is non-empty, the column values are used to control pagination.
+   * <p>If {@code orderByKeys} is non-empty, they refer to the columns that must uniquely identify
+   * a row. These column values are then used to control pagination.
    * For example, if {@code [groupId, timestamp]} can uniquely identify a row, the generated
    * SQL will use {@code "groupId" > ? OR ("groupId" = ? AND "timestamp" > ?)} for the next page,
    * comparing against the previous page's last row.
@@ -1099,10 +1106,11 @@ public <T> Stream<List<T>> paginateLazily(
    * 
    * <p>The standard SQL {@code FETCH NEXT ROWS} syntax is used for pagination.
    * If {@code orderByKeys} is empty, the paginated query will use {@code OFFSET} keyword
-   * to specify the next page offset.
+   * instead of the sort key columns to specify the next page offset.
    * 
-   * <p>All column names are automatically double-quoted to avoid clashing with keywords or spaces
-   * in identifiers. If your DB is case sensitive, make sure you pass in the accurate case.
+   * <p>The {@code orderByKeys} column names are automatically double-quoted to avoid clashing
+   * with keywords or spaces in identifiers. 
+   * If your DB is case sensitive, make sure you pass in the accurate case.
    * 
    * <p>The method is lazy. Paginated queries are only sent when the returned stream is consumed.
    * The caller should close the {@code connection} after done, which will close the cached