Update docs for GEOSEARCH command (valkey-io#2017)

* Update docs.

Signed-off-by: Yury-Fridlyand <yury.fridlyand@improving.com>
Co-authored-by: Aaron <69273634+aaron-congo@users.noreply.github.com>

CHANGELOG.md

@@ -1,4 +1,5 @@
 #### Changes
+* Java, Python: Update docs for GEOSEARCH command ([#2017](https://github.com/valkey-io/valkey-glide/pull/2017))
 * Node: Added FUNCTION LIST command ([#2019](https://github.com/valkey-io/valkey-glide/pull/2019))
 * Node: Added GEOSEARCH command ([#2007](https://github.com/valkey-io/valkey-glide/pull/2007))
 * Node: Added LMOVE command ([#2002](https://github.com/valkey-io/valkey-glide/pull/2002))

java/client/src/main/java/glide/api/models/commands/geospatial/GeoSearchOptions.java

@@ -11,11 +11,11 @@
  * GeoSearchOrigin.SearchOrigin, GeoSearchShape, GeoSearchOptions)} command, options include:
  *
  * <ul>
- *   <li>WITHDIST: Also return the distance of the returned items from the specified center point.
- *       The distance is returned in the same unit as specified for the <code>searchBy
- *           </code> argument.
- *   <li>WITHCOORD: Also return the coordinate of the returned items.
- *   <li>WITHHASH: Also return the geohash of the returned items. for the general user.
+ *   <li><code>WITHDIST</code>: Also return the distance of the returned items from the specified
+ *       center point. The distance is returned in the same unit as specified for the <code>searchBy
+ *       </code> argument.
+ *   <li><code>WITHCOORD</code>: Also return the coordinate of the returned items.
+ *   <li><code>WITHHASH</code>: Also return the geohash of the returned items.
  * </ul>
  *
  * @see <a href="https://valkey.io/commands/geosearch/">valkey.io</a>

java/client/src/main/java/glide/api/models/commands/geospatial/GeoSearchOrigin.java

@@ -15,7 +15,7 @@ public final class GeoSearchOrigin {
     /** Valkey API keyword used to perform search from the position of a given member. */
     public static final String FROMMEMBER_VALKEY_API = "FROMMEMBER";
 
-    /** Valkey API keyword used to perform search from the given longtitude & latitue position. */
+    /** Valkey API keyword used to perform search from the given longitude & latitude position. */
     public static final String FROMLONLAT_VALKEY_API = "FROMLONLAT";
 
     /**
@@ -36,12 +36,6 @@ public interface SearchOrigin {
     public static class CoordOrigin implements SearchOrigin {
         private final GeospatialData position;
 
-        /**
-         * Converts GeoSearchOrigin into a String[].
-         *
-         * @return String[] An array containing arguments corresponding to the starting point of the
-         *     query.
-         */
         public String[] toArgs() {
             return ArrayUtils.addAll(new String[] {FROMLONLAT_VALKEY_API}, position.toArgs());
         }
@@ -52,12 +46,6 @@ public String[] toArgs() {
     public static class MemberOrigin implements SearchOrigin {
         private final String member;
 
-        /**
-         * Converts GeoSearchOrigin into a String[].
-         *
-         * @return String[] An array containing arguments corresponding to the starting point of the
-         *     query.
-         */
         public String[] toArgs() {
             return new String[] {FROMMEMBER_VALKEY_API, member};
         }
@@ -68,12 +56,6 @@ public String[] toArgs() {
     public static class MemberOriginBinary implements SearchOrigin {
         private final GlideString member;
 
-        /**
-         * Converts GeoSearchOrigin into a String[].
-         *
-         * @return String[] An array containing arguments corresponding to the starting point of the
-         *     query.
-         */
         public String[] toArgs() {
             return new String[] {FROMMEMBER_VALKEY_API, member.toString()};
         }

java/client/src/main/java/glide/api/models/commands/geospatial/GeoSearchResultOptions.java

@@ -8,20 +8,16 @@
 
 /**
  * Optional arguments for {@link GeospatialIndicesBaseCommands#geosearch(String,
- * GeoSearchOrigin.SearchOrigin, GeoSearchShape, GeoSearchOptions)} command that contains up to 2
- * optional input, including:
+ * GeoSearchOrigin.SearchOrigin, GeoSearchShape, GeoSearchOptions)} command that contains up to 3
+ * optional inputs, including:
  *
  * <ul>
- *   <li>SortOrder: The query's order to sort the results by:
- *       <ul>
- *         <li>ASC: Sort returned items from the nearest to the farthest, relative to the center
- *             point.
- *         <li>DESC: Sort returned items from the farthest to the nearest, relative to the center
- *             point.
- *       </ul>
- *   <li>COUNT: Limits the results to the first N matching items, when the 'ANY' option is used, the
- *       command returns as soon as enough matches are found. This means that the results might may
- *       not be the ones closest to the origin.
+ *   <li>{@link SortOrder} to order the search results by the distance to the center point of the
+ *       search area.
+ *   <li><code>COUNT</code> to limit the number of search results.
+ *   <li><code>ANY</code>, which can only be used if <code>COUNT</code> is also provided. This
+ *       option makes the command return as soon as enough matches are found. This means that the
+ *       results might not be the ones closest to the origin.
  * </ul>
  *
  * @see <a href="https://valkey.io/commands/geosearch/">valkey.io</a>
@@ -42,38 +38,40 @@ public class GeoSearchResultOptions {
     /** Indicates the number of matches the result should be limited to. */
     private final long count;
 
-    /** Indicates if the 'ANY' keyword is used for 'COUNT'. */
+    /** Whether to allow returning as soon as enough matches are found. */
     private final boolean isAny;
 
-    /** Constructor with count only. */
+    /** Define number of search results. */
     public GeoSearchResultOptions(long count) {
         this.sortOrder = null;
         this.count = count;
         this.isAny = false;
     }
 
-    /** Constructor with count and the 'ANY' keyword. */
+    /**
+     * Define number of search results, and whether or not the <code>ANY</code> option should be used.
+     */
     public GeoSearchResultOptions(long count, boolean isAny) {
         this.sortOrder = null;
         this.count = count;
         this.isAny = isAny;
     }
 
-    /** Constructor with sort order only. */
+    /** Define the sort order only. */
     public GeoSearchResultOptions(SortOrder order) {
         this.sortOrder = order;
         this.count = -1;
         this.isAny = false;
     }
 
-    /** Constructor with sort order and count. */
+    /** Define the sort order and count. */
     public GeoSearchResultOptions(SortOrder order, long count) {
         this.sortOrder = order;
         this.count = count;
         this.isAny = false;
     }
 
-    /** Constructor with sort order, count and 'ANY' keyword. */
+    /** Configure all parameters. */
     public GeoSearchResultOptions(SortOrder order, long count, boolean isAny) {
         this.sortOrder = order;
         this.count = count;

java/client/src/main/java/glide/api/models/commands/geospatial/GeoSearchShape.java

@@ -2,54 +2,33 @@
 package glide.api.models.commands.geospatial;
 
 import glide.api.commands.GeospatialIndicesBaseCommands;
-import lombok.Getter;
 
 /**
  * The query's shape for {@link GeospatialIndicesBaseCommands} command.
  *
  * @see <a href="https://valkey.io/commands/geosearch/">valkey.io</a>
  */
-@Getter
 public final class GeoSearchShape {
-    /** Valkey API keyword used to perform geosearch by radius. */
-    public static final String BYRADIUS_VALKEY_API = "BYRADIUS";
 
-    /** Valkey API keyword used to perform geosearch by box. */
-    public static final String BYBOX_VALKEY_API = "BYBOX";
-
-    /**
-     * The geosearch query's shape:
-     *
-     * <ul>
-     *   <li>BYRADIUS - Circular shaped query.
-     *   <li>BYBOX - Box shaped query.
-     * </ul>
-     */
-    public enum SearchShape {
+    /** The geosearch query's shape. */
+    enum SearchShape {
+        /** Circular shaped query. */
         BYRADIUS,
+        /** Rectangular shaped query. */
         BYBOX
     }
 
-    /** The geosearch query's shape. */
     private final SearchShape shape;
-
-    /** The circular geosearch query's radius. */
     private final double radius;
-
-    /** The box geosearch query's width. */
     private final double width;
-
-    /** The box geosearch query's height. */
     private final double height;
-
-    /** The geosearch query's metric unit. */
     private final GeoUnit unit;
 
     /**
-     * BYRADIUS constructor for GeoSearchShape
+     * Defines a circular search area.
      *
      * @param radius The radius to search by.
-     * @param unit The unit of the radius.
+     * @param unit The measurement unit of the radius.
      */
     public GeoSearchShape(double radius, GeoUnit unit) {
         this.shape = SearchShape.BYRADIUS;
@@ -62,11 +41,11 @@ public GeoSearchShape(double radius, GeoUnit unit) {
     }
 
     /**
-     * BYBOX constructor for GeoSearchShape
+     * Defines a rectangular search area.
      *
      * @param width The width to search by.
      * @param height The height to search by.
-     * @param unit The unit of the radius.
+     * @param unit The measurement unit of the width and height.
      */
     public GeoSearchShape(double width, double height, GeoUnit unit) {
         this.shape = SearchShape.BYBOX;
@@ -91,7 +70,7 @@ public String[] toArgs() {
                 return new String[] {
                     shape.toString(), Double.toString(width), Double.toString(height), unit.getValkeyAPI()
                 };
-            default:
+            default: // unreachable
                 return new String[] {};
         }
     }

java/client/src/main/java/glide/api/models/commands/geospatial/GeoSearchStoreOptions.java

@@ -12,16 +12,10 @@
  */
 @Builder
 public final class GeoSearchStoreOptions {
-    /**
-     * Valkey API keyword used to perform geosearchstore and optionally sort the results with their
-     * distance from the center.
-     */
+    /** Valkey API keyword for {@link #storeDist} parameter. */
     public static final String GEOSEARCHSTORE_VALKEY_API = "STOREDIST";
 
-    /**
-     * boolean value indicating if the STOREDIST option should be included. Can be included in builder
-     * construction by using {@link GeoSearchStoreOptionsBuilder#storedist()}.
-     */
+    /** Configure sorting the results with their distance from the center. */
     private final boolean storeDist;
 
     /**
@@ -40,6 +34,7 @@ public String[] toArgs() {
     public static class GeoSearchStoreOptionsBuilder {
         public GeoSearchStoreOptionsBuilder() {}
 
+        /** Enable sorting the results with their distance from the center. */
         public GeoSearchStoreOptionsBuilder storedist() {
             return storeDist(true);
         }

java/client/src/main/java/glide/api/models/commands/geospatial/GeoUnit.java

@@ -1,14 +1,10 @@
 /** Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0 */
 package glide.api.models.commands.geospatial;
 
-import glide.api.commands.GeospatialIndicesBaseCommands;
 import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 
-/**
- * Enumeration representing distance units options for the {@link
- * GeospatialIndicesBaseCommands#geodist(String, String, String, GeoUnit)} command.
- */
+/** Enumeration representing distance units options for the geospatial command. */
 @RequiredArgsConstructor
 @Getter
 public enum GeoUnit {