Skip to content

Apache Lucene open-source search software

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

Ankit Jainbb8b1397b014
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt
index 9dca1db2c27..e06262af574 100644
--- a/lucene/CHANGES.txt
+++ b/lucene/CHANGES.txt
@@ -81,10 +81,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)
diff --git a/lucene/core/src/java/org/apache/lucene/geo/Circle.java b/lucene/core/src/java/org/apache/lucene/geo/Circle.java
index 9d5357a7111..c079b8000dd 100644
--- a/lucene/core/src/java/org/apache/lucene/geo/Circle.java
+++ b/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.. */
diff --git a/lucene/core/src/java/org/apache/lucene/geo/GeoUtils.java b/lucene/core/src/java/org/apache/lucene/geo/GeoUtils.java
index 7f7278d066c..16c2ecd80f4 100644
--- a/lucene/core/src/java/org/apache/lucene/geo/GeoUtils.java
+++ b/lucene/core/src/java/org/apache/lucene/geo/GeoUtils.java
@@ -23,7 +23,28 @@ import org.apache.lucene.index.PointValues.Relation;
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
*/
diff --git a/lucene/core/src/java/org/apache/lucene/geo/Rectangle.java b/lucene/core/src/java/org/apache/lucene/geo/Rectangle.java
index 6435d745243..63fa0a17422 100644
--- a/lucene/core/src/java/org/apache/lucene/geo/Rectangle.java
+++ b/lucene/core/src/java/org/apache/lucene/geo/Rectangle.java
@@ -32,18 +32,51 @@ import static org.apache.lucene.util.SloppyMath.asin;
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;
/**
diff --git a/lucene/core/src/java/org/apache/lucene/geo/package-info.java b/lucene/core/src/java/org/apache/lucene/geo/package-info.java
index b0e6d3224e2..bb34fa8daea 100644
--- a/lucene/core/src/java/org/apache/lucene/geo/package-info.java
+++ b/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;