From 4f6501f140a25ae53c1edbf14f9bde4947f0bfc8 Mon Sep 17 00:00:00 2001
From: Christoph Strobl <cstrobl@vmware.com>
Date: Wed, 9 Feb 2022 14:38:27 +0100
Subject: [PATCH] Update GeoJson section in reference documentation.

Mention the relation of Point/GeoJsonPoint x/y coordinates to longitude/latitude.

Original Pull Request: #3956
---
 .../data/mongodb/core/geo/GeoJsonPoint.java        | 14 +++++++++++---
 src/main/asciidoc/reference/mongodb.adoc           |  6 ++++++
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/geo/GeoJsonPoint.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/geo/GeoJsonPoint.java
index e9c7efd9b..8b0c32d3b 100644
--- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/geo/GeoJsonPoint.java
+++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/geo/GeoJsonPoint.java
@@ -21,7 +21,8 @@ import java.util.List;
 import org.springframework.data.geo.Point;
 
 /**
- * {@link GeoJson} representation of {@link Point}.
+ * {@link GeoJson} representation of {@link Point}. Uses {@link Point#getX()} as {@literal longitude} and
+ * {@link Point#getY()} as {@literal latitude}.
  *
  * @author Christoph Strobl
  * @since 1.7
@@ -36,8 +37,8 @@ public class GeoJsonPoint extends Point implements GeoJson<List<Double>> {
 	/**
 	 * Creates {@link GeoJsonPoint} for given coordinates.
 	 *
-	 * @param x : longitude
-	 * @param y : latitude
+	 * @param x longitude between {@literal -180} and {@literal 180} (inclusive).
+	 * @param y latitude between {@literal -90} and {@literal 90} (inclusive).
 	 */
 	public GeoJsonPoint(double x, double y) {
 		super(x, y);
@@ -45,6 +46,8 @@ public class GeoJsonPoint extends Point implements GeoJson<List<Double>> {
 
 	/**
 	 * Creates {@link GeoJsonPoint} for given {@link Point}.
+	 * <p>
+	 * {@link Point#getX()} translates to {@literal longitude}, {@link Point#getY()} to {@literal latitude}.
 	 *
 	 * @param point must not be {@literal null}.
 	 */
@@ -57,6 +60,11 @@ public class GeoJsonPoint extends Point implements GeoJson<List<Double>> {
 		return TYPE;
 	}
 
+	/**
+	 * Obtain the coordinates (x/longitude, y/latitude) array.
+	 *
+	 * @return the coordinates putting {@link #getX() x/longitude} first, and {@link #getY() y/latitude} second.
+	 */
 	@Override
 	public List<Double> getCoordinates() {
 		return Arrays.asList(Double.valueOf(getX()), Double.valueOf(getY()));
diff --git a/src/main/asciidoc/reference/mongodb.adoc b/src/main/asciidoc/reference/mongodb.adoc
index 3227ba176..98aeaa8e9 100644
--- a/src/main/asciidoc/reference/mongodb.adoc
+++ b/src/main/asciidoc/reference/mongodb.adoc
@@ -1537,6 +1537,12 @@ public class Store {
 ----
 ====
 
+[TIP]
+====
+If the `coordinates` of a GeoJSON object represent _latitude_ and _longitude_ pairs, the _longitude_ goes first followed by _latitude_. +
+`GeoJsonPoint` therefore treats `getX()` as _longitude_ and `getY()` as _latitude_.
+====
+
 [[mongo.geo-json.query-methods]]
 ==== GeoJSON Types in Repository Query Methods