Improve user-facing docs for geo package (#14534)

Author: jainankitk

lucene/CHANGES.txt

@@ -22,10 +22,12 @@ New Features
 
 Improvements
 ---------------------
-* GITHUB#14458 : Add an IndexDeletion policy that retains the last N commits. (Owais Kazi)
+* GITHUB#14458: Add an IndexDeletion policy that retains the last N commits. (Owais Kazi)
 
 * GITHUB#14476: Removing unnecessary splitX in ComponentTree (Ankit Jain)
 
+* GITHUB#14534: Improve user-facing docs for geo package (Ankit Jain)
+
 * GITHUB#14602: Refactor the expressions compiler to use official ClassData BSM with indexed lookup
   (Uwe Schindler)
 

lucene/core/src/java/org/apache/lucene/geo/Circle.java

@@ -17,27 +17,43 @@
 package org.apache.lucene.geo;
 
 /**
- * Represents a circle on the earth's surface.
+ * Represents a circle on the Earth's surface defined by a center point and radius.
  *
- * <p>NOTES:
+ * <p>The circle is defined using:
  *
- * <ol>
- *   <li>Latitude/longitude values must be in decimal degrees.
- *   <li>Radius must be in meters.
- *   <li>For more advanced GeoSpatial indexing and query operations see the {@code spatial-extras}
- *       module
- * </ol>
+ * <ul>
+ *   <li>Center point (latitude/longitude in degrees)
+ *   <li>Radius in meters
+ * </ul>
+ *
+ * <p>Important Notes:
+ *
+ * <ul>
+ *   <li>The circle is approximated on the spherical Earth model
+ *   <li>For very large circles or circles near poles, consider using polygons instead
+ *   <li>Dateline crossing is handled automatically
+ * </ul>
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * // Create a circle with 1km radius around the Eiffel Tower
+ * Circle circle = new Circle(48.8584, 2.2945, 1000);
+ *
+ * // Create a query using this circle
+ * Query query = LatLonShape.newDistanceQuery("location", circle);
+ * }</pre>
  *
  * @lucene.experimental
  */
 public final class Circle extends LatLonGeometry {
-  /** Center latitude */
+  /** Center latitude of the circle in degrees (-90 to 90) */
   private final double lat;
 
-  /** Center longitude */
+  /** Center longitude of the circle in degrees (-180 to 180) */
   private final double lon;
 
-  /** radius in meters */
+  /** radius of the circle in meters */
   private final double radiusMeters;
 
   /** Creates a new circle from the supplied latitude/longitude center and a radius in meters.. */

lucene/core/src/java/org/apache/lucene/geo/GeoUtils.java

@@ -23,7 +23,28 @@
 import org.apache.lucene.util.SloppyMath;
 
 /**
- * Basic reusable geo-spatial utility methods
+ * Utility methods for geo-spatial calculations and coordinate validation.
+ *
+ * <p>This class provides:
+ *
+ * <ul>
+ *   <li>Coordinate validation methods
+ *   <li>Earth model constants
+ *   <li>Common geometric calculations
+ *   <li>Coordinate normalization utilities
+ * </ul>
+ *
+ * <p>Important Constants:
+ *
+ * <ul>
+ *   <li>Earth's mean radius: 6,371,008.7714 meters
+ *   <li>Latitude range: -90° to +90°
+ *   <li>Longitude range: -180° to +180°
+ * </ul>
+ *
+ * <p>Note: This class uses a spherical Earth model for simplicity and performance. For applications
+ * requiring higher precision, consider using a geodetic library that implements the WGS84 ellipsoid
+ * model.
  *
  * @lucene.experimental
  */

lucene/core/src/java/org/apache/lucene/geo/Rectangle.java

@@ -32,18 +32,51 @@
 import static org.apache.lucene.util.SloppyMath.cos;
 import static org.apache.lucene.util.SloppyMath.sin;
 
-/** Represents a lat/lon rectangle. */
+/**
+ * Represents a rectangular bounding box on Earth's surface.
+ *
+ * <p>A rectangle is defined by its minimum and maximum latitude/longitude coordinates. It can cross
+ * the dateline, in which case minLon &gt; maxLon.
+ *
+ * <p>Key Features:
+ *
+ * <ul>
+ *   <li>Handles dateline crossing automatically
+ *   <li>Supports point-in-box testing
+ *   <li>Can be used to create spatial queries
+ *   <li>Useful for creating bounding boxes around other shapes
+ * </ul>
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * // Create a rectangle covering central London
+ * Rectangle bbox = new Rectangle(51.4, 51.6, -0.2, 0.0);
+ *
+ * // Create a rectangle crossing the dateline
+ * Rectangle datelineBox = new Rectangle(20, 30, 170, -170);
+ *
+ * // Create a bounding box around a point with given radius
+ * Rectangle circle = Rectangle.fromPointDistance(lat, lon, radiusMeters);
+ * }</pre>
+ *
+ * <p>Note: When working with areas near poles, consider that rectangles become highly distorted and
+ * may not provide accurate representation of the actual area.
+ */
 public class Rectangle extends LatLonGeometry {
-  /** maximum longitude value (in degrees) */
+  /** Minimum latitude in degrees (-90 to 90) */
   public final double minLat;
 
-  /** minimum longitude value (in degrees) */
-  public final double minLon;
-
-  /** maximum latitude value (in degrees) */
+  /** Maximum latitude in degrees (-90 to 90) */
   public final double maxLat;
 
-  /** minimum latitude value (in degrees) */
+  /**
+   * Minimum longitude in degrees (-180 to 180). May be greater than maxLon when crossing the
+   * dateline.
+   */
+  public final double minLon;
+
+  /** Maximum longitude in degrees (-180 to 180) */
   public final double maxLon;
 
   /**

lucene/core/src/java/org/apache/lucene/geo/package-info.java

@@ -15,5 +15,54 @@
  * limitations under the License.
  */
 
-/** Geospatial Utility Implementations for Lucene Core */
+/**
+ * Core geo-spatial types and utilities for handling geographical data and spatial operations in
+ * Lucene.
+ *
+ * <h2>Overview</h2>
+ *
+ * This package provides classes for representing, indexing, and querying geographical data in
+ * Lucene. It uses the WGS84 coordinate system with latitude/longitude pairs to represent points on
+ * Earth.
+ *
+ * <h2>Core Concepts</h2>
+ *
+ * <ul>
+ *   <li>Coordinate System: WGS84 (World Geodetic System 1984)
+ *       <ul>
+ *         <li>Latitude: -90° to +90° (negative for South, positive for North)
+ *         <li>Longitude: -180° to +180° (negative for West, positive for East)
+ *       </ul>
+ *   <li>Distance calculations use haversine formula on a spherical Earth model
+ *   <li>Areas near poles and the dateline receive special handling
+ * </ul>
+ *
+ * <h2>Key Components</h2>
+ *
+ * <ul>
+ *   <li>{@link org.apache.lucene.geo.Point}: Represents a point on Earth's surface
+ *   <li>{@link org.apache.lucene.geo.Rectangle}: Defines a bounding box for spatial queries
+ *   <li>{@link org.apache.lucene.geo.Circle}: Represents a circular area with a center point and
+ *       radius
+ *   <li>{@link org.apache.lucene.geo.Polygon}: Represents an arbitrary polygon shape
+ *   <li>{@link org.apache.lucene.geo.Line}: Represents a path or line string
+ * </ul>
+ *
+ * <h2>Common Operations</h2>
+ *
+ * <ul>
+ *   <li>Distance calculations between points
+ *   <li>Point-in-polygon testing
+ *   <li>Rectangle containment and intersection
+ *   <li>Creation of bounding boxes
+ *   <li>Polygon validation and preprocessing
+ * </ul>
+ *
+ * <h2>Usage Examples</h2>
+ *
+ * <pre>{@code
+ * Rectangle bbox = Rectangle.fromPointDistance(51.5, -0.12, 5000); // 5km around London
+ * Circle circle = new Circle(48.8566, 2.3522, 1000); // 1km around Paris
+ * }</pre>
+ */
 package org.apache.lucene.geo;