clarify point.distance function (#1064)

Author: JPryce-Aklundh

modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc

@@ -301,7 +301,9 @@ Either the pattern already exists, or it needs to be created.
 | Returns a 2D or 3D point object, given two or respectively three coordinate values in the Cartesian coordinate system or WGS 84 geographic coordinate system.
 
 | xref:functions/spatial.adoc#functions-point-distance[`point.distance()`]
-| Returns a `FLOAT` representing the geodesic distance between any two points in the same CRS.
+| Returns a `FLOAT` representing the distance between any two points in the same CRS.
+If the points are in the WGS 84 CRS, the function returns the geodesic distance (i.e., the shortest path along the curved surface of the Earth).
+If the points are in a Cartesian CRS, the function returns the Euclidean distance (i.e., the shortest straight-line distance in a flat, planar space).
 
 | xref:functions/spatial.adoc#functions-point-withinBBox[`point.withinBBox()`]
 | Returns true if the provided point is within the bounding box defined by the two provided points.

modules/ROOT/pages/functions/index.adoc

@@ -573,7 +573,9 @@ These functions are used to specify 2D or 3D points in a geographic or cartesian
 
 1.1+| xref::functions/spatial.adoc#functions-distance[`point.distance()`]
 | `point.distance(from :: POINT, to :: POINT) :: FLOAT`
-| Returns a `FLOAT` representing the geodesic distance between any two points in the same CRS.
+| Returns a `FLOAT` representing the distance between any two points in the same CRS.
+If the points are in the WGS 84 CRS, the function returns the geodesic distance (i.e., the shortest path along the curved surface of the Earth).
+If the points are in a Cartesian CRS, the function returns the Euclidean distance (i.e., the shortest straight-line distance in a flat, planar space).
 
 1.1+| xref::functions/spatial.adoc#functions-withinBBox[`point.withinBBox()`]
 | `point.withinBBox(point :: POINT, lowerLeft :: POINT, upperRight :: POINT) :: BOOLEAN`

modules/ROOT/pages/functions/spatial.adoc

@@ -250,7 +250,9 @@ If `null` is provided as the argument, `null` is returned.
 .Details
 |===
 | *Syntax* 3+| `point.distance(from, to)`
-| *Description* 3+| Returns a `FLOAT` representing the geodesic distance between any two points in the same CRS.
+| *Description* 3+| Returns a `FLOAT` representing the distance between any two points in the same CRS.
+If the points are in the WGS 84 CRS, the function returns the geodesic distance (i.e., the shortest path along the curved surface of the Earth).
+If the points are in a Cartesian CRS, the function returns the Euclidean distance (i.e., the shortest straight-line distance in a flat, planar space).
 .3+| *Arguments* | *Name* | *Type* | *Description*
 | `from` | `POINT` | A start point.
 | `to` | `POINT` | An end point in the same CRS as the start point.