chore: document SortBy usage

Author: bevzzz

src/main/java/io/weaviate/client6/v1/api/collections/query/FetchObjects.java

@@ -21,10 +21,30 @@ public FetchObjects(Builder builder) {
   public static class Builder extends BaseQueryOptions.Builder<Builder, FetchObjects> {
     private final List<SortBy> sortBy = new ArrayList<>();
 
+    /**
+     * Sort query results. Default sorted order is ascending, use
+     * {@link SortBy#desc} to reverse it.
+     *
+     * <pre>{@code
+     * sort(SortBy.property("age"), SortBy.creationTime().desc());
+     * }</pre>
+     *
+     * @param sortBy A list of sort-by clauses in the order
+     *               they should be applied.
+     * @return This builder.
+     */
     public Builder sort(SortBy... sortBy) {
       return sort(Arrays.asList(sortBy));
     }
 
+    /**
+     * Sort query results. Default sorted order is ascending, use
+     * {@link SortBy#desc} to reverse it.
+     *
+     * @param sortBy A list of sort-by clauses in the order
+     *               they should be applied.
+     * @return This builder.
+     */
     public Builder sort(List<SortBy> sortBy) {
       this.sortBy.addAll(sortBy);
       return this;

src/main/java/io/weaviate/client6/v1/api/collections/query/SortBy.java

@@ -3,22 +3,57 @@
 import java.util.List;
 
 public record SortBy(List<String> path, boolean ascending) {
+  /**
+   * Sort by object property. Ascending order by default.
+   *
+   * @see #desc() to sort in descending order.
+   */
   public static SortBy property(String property) {
     return new SortBy(List.of(property), true);
   }
 
+  /**
+   * Sort by object creation time. Ascending order by default.
+   *
+   * @see #desc() to sort in descending order.
+   */
   public static SortBy creationTime() {
     return property("_creationTimeUnix");
   }
 
+  /**
+   * Sort by object last update time. Ascending order by default.
+   *
+   * @see #desc() to sort in descending order.
+   */
   public static SortBy lastUpdateTime() {
     return property("_lastUpdateTimeUnix");
   }
 
+  /**
+   * Sort in ascending order.
+   *
+   * <p>
+   * Example:
+   *
+   * <pre>{@code
+   * SortBy.property("name").asc();
+   * }</pre>
+   */
   public SortBy asc() {
     return new SortBy(path, true);
   }
 
+  /**
+   * Sort in descending order.
+   *
+   * <p>
+   * Example:
+   *
+   * <pre>{@code
+   * SortBy.property("name").desc();
+   * }</pre>
+   */
   public SortBy desc() {
     return new SortBy(path, false);
   }