More explicit documentation of geometry classes, with warnings

that calculations are Cartesian only and point users to QgsDistanceArea
for ellipsoidal calculations

Fixes #31275

python/core/auto_generated/geometry/qgsabstractgeometry.sip.in

@@ -22,6 +22,16 @@ class QgsAbstractGeometry
 %Docstring
 Abstract base class for all geometries
 
+.. note::
+
+   QgsAbstractGeometry objects are inherently Cartesian/planar geometries. They have no concept of geodesy, and none
+   of the methods or properties exposed from the QgsAbstractGeometry API (or QgsGeometry API) utilise
+   geodesic calculations. Accordingly, properties like length() and area() and spatial operations like centroid()
+   are always calculated using strictly Cartesian mathematics. In contrast, the QgsDistanceArea class exposes
+   methods for working with geodesic calculations and spatial operations on geometries,
+   and should be used whenever calculations which account for the curvature of the Earth (or any other celestial body)
+   are required.
+
 .. versionadded:: 2.10
 %End
 
@@ -400,7 +410,15 @@ Deletes a vertex within the geometry
 
     virtual double length() const;
 %Docstring
-Returns the length of the geometry.
+Returns the planar, 2-dimensional length of the geometry.
+
+.. warning::
+
+   QgsAbstractGeometry objects are inherently Cartesian/planar geometries, and the length
+   returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+   the QgsDistanceArea class exposes methods for calculating the lengths of geometries using
+   geodesic calculations which account for the curvature of the Earth (or any other
+   celestial body).
 
 .. seealso:: :py:func:`area`
 
@@ -409,7 +427,15 @@ Returns the length of the geometry.
 
     virtual double perimeter() const;
 %Docstring
-Returns the perimeter of the geometry.
+Returns the planar, 2-dimensional perimeter of the geometry.
+
+.. warning::
+
+   QgsAbstractGeometry objects are inherently Cartesian/planar geometries, and the perimeter
+   returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+   the QgsDistanceArea class exposes methods for calculating the perimeters of geometries using
+   geodesic calculations which account for the curvature of the Earth (or any other
+   celestial body).
 
 .. seealso:: :py:func:`area`
 
@@ -418,7 +444,15 @@ Returns the perimeter of the geometry.
 
     virtual double area() const;
 %Docstring
-Returns the area of the geometry.
+Returns the planar, 2-dimensional area of the geometry.
+
+.. warning::
+
+   QgsAbstractGeometry objects are inherently Cartesian/planar geometries, and the area
+   returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+   the QgsDistanceArea class exposes methods for calculating the areas of geometries using
+   geodesic calculations which account for the curvature of the Earth (or any other
+   celestial body).
 
 .. seealso:: :py:func:`length`
 
@@ -429,6 +463,11 @@ Returns the area of the geometry.
 %Docstring
 Returns the length of the segment of the geometry which begins at ``startVertex``.
 
+.. warning::
+
+   QgsAbstractGeometry objects are inherently Cartesian/planar geometries, and the lengths
+   returned by this method are calculated using strictly Cartesian mathematics.
+
 .. versionadded:: 3.0
 %End
 

python/core/auto_generated/geometry/qgsgeometry.sip.in

@@ -29,16 +29,28 @@ typedef QVector<QVector<QVector<QgsPointXY>>> QgsMultiPolygonXY;
 
 
 
-
 class QgsGeometry
 {
 %Docstring
-A geometry is the spatial representation of a feature. Since QGIS 2.10, QgsGeometry acts as a generic container
-for geometry objects. QgsGeometry is implicitly shared, so making copies of geometries is inexpensive. The geometry
-container class can also be stored inside a QVariant object.
+A geometry is the spatial representation of a feature.
+
+QgsGeometry acts as a generic container for geometry objects. QgsGeometry objects are implicitly shared,
+so making copies of geometries is inexpensive. The geometry container class can also be stored inside
+a QVariant object.
 
 The actual geometry representation is stored as a QgsAbstractGeometry within the container, and
-can be accessed via the get() method or set using the set() method.
+can be accessed via the get() method or set using the set() method. This gives access to the underlying
+raw geometry primitive, such as the point, line, polygon, curve or other geometry subclasses.
+
+.. note::
+
+   QgsGeometry objects are inherently Cartesian/planar geometries. They have no concept of geodesy, and none
+   of the methods or properties exposed from the QgsGeometry API (or QgsAbstractGeometry subclasses) utilise
+   geodesic calculations. Accordingly, properties like length() and area() or spatial operations like buffer()
+   are always calculated using strictly Cartesian mathematics. In contrast, the QgsDistanceArea class exposes
+   methods for working with geodesic calculations and spatial operations on geometries,
+   and should be used whenever calculations which account for the curvature of the Earth (or any other celestial body)
+   are required.
 %End
 
 %TypeHeaderCode
@@ -345,24 +357,47 @@ Uses GEOS library for the test.
 
     double area() const;
 %Docstring
-Returns the area of the geometry using GEOS
+Returns the planar, 2-dimensional area of the geometry.
+
+.. warning::
+
+   QgsGeometry objects are inherently Cartesian/planar geometries, and the area
+   returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+   the QgsDistanceArea class exposes methods for calculating the areas of geometries using
+   geodesic calculations which account for the curvature of the Earth (or any other
+   celestial body).
+
+.. seealso:: :py:func:`length`
 
 .. versionadded:: 1.5
 %End
 
     double length() const;
 %Docstring
-Returns the length of geometry using GEOS
+Returns the planar, 2-dimensional length of geometry.
+
+.. warning::
+
+   QgsGeometry objects are inherently Cartesian/planar geometries, and the length
+   returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+   the QgsDistanceArea class exposes methods for calculating the lengths of geometries using
+   geodesic calculations which account for the curvature of the Earth (or any other
+   celestial body).
+
+.. seealso:: :py:func:`area`
 
 .. versionadded:: 1.5
 %End
 
     double distance( const QgsGeometry &geom ) const;
 %Docstring
-Returns the minimum distance between this geometry and another geometry, using GEOS.
-Will return a negative value if a geometry is missing.
+Returns the minimum distance between this geometry and another geometry.
+Will return a negative value if either geometry is empty or null.
 
-:param geom: geometry to find minimum distance to
+.. warning::
+
+   QgsGeometry objects are inherently Cartesian/planar geometries, and the distance
+   returned by this method is calculated using strictly Cartesian mathematics.
 %End
 
 
@@ -533,6 +568,11 @@ Returns the distance along this geometry from its first vertex to the specified
 
 :return: distance to vertex (following geometry), or -1 for invalid vertex numbers
 
+.. warning::
+
+   QgsGeometry objects are inherently Cartesian/planar geometries, and the distance
+   returned by this method is calculated using strictly Cartesian mathematics.
+
 .. versionadded:: 2.16
 %End
 
@@ -654,6 +694,12 @@ Returns the shortest line joining this geometry to another geometry.
 
 .. seealso:: :py:func:`nearestPoint`
 
+.. warning::
+
+   QgsGeometry objects are inherently Cartesian/planar geometries, and the line
+   returned by this method is calculated using strictly Cartesian mathematics. See :py:class:`QgsDistanceArea`
+   for similar methods which account for the curvature of an ellipsoidal body such as the Earth.
+
 .. versionadded:: 2.14
 %End
 
@@ -953,47 +999,48 @@ geometries.
 
     bool contains( const QgsPointXY *p ) const;
 %Docstring
-Tests for containment of a point (uses GEOS)
+Returns ``True`` if the geometry contains the point ``p``.
 %End
 
     bool contains( const QgsGeometry &geometry ) const;
 %Docstring
-Tests for if geometry is contained in another (uses GEOS)
+Returns ``True`` if the geometry completely contains another ``geometry``.
 
 .. versionadded:: 1.5
 %End
 
     bool disjoint( const QgsGeometry &geometry ) const;
 %Docstring
-Tests for if geometry is disjoint of another (uses GEOS)
+Returns ``True`` if the geometry is disjoint of another ``geometry``.
 
 .. versionadded:: 1.5
 %End
 
     bool touches( const QgsGeometry &geometry ) const;
 %Docstring
-Test for if geometry touch another (uses GEOS)
+Returns ``True`` if the geometry touches another ``geometry``.
 
 .. versionadded:: 1.5
 %End
 
     bool overlaps( const QgsGeometry &geometry ) const;
 %Docstring
-Test for if geometry overlaps another (uses GEOS)
+Returns ``True`` if the geometry overlaps another ``geometry``.
 
 .. versionadded:: 1.5
 %End
 
     bool within( const QgsGeometry &geometry ) const;
 %Docstring
-Test for if geometry is within another (uses GEOS)
+Returns ``True`` if the geometry is completely within another ``geometry``.
 
 .. versionadded:: 1.5
 %End
 
+
     bool crosses( const QgsGeometry &geometry ) const;
 %Docstring
-Test for if geometry crosses another (uses GEOS)
+Returns ``True`` if the geometry crosses another ``geometry``.
 
 .. versionadded:: 1.5
 %End

python/core/auto_generated/geometry/qgspoint.sip.in

@@ -207,7 +207,7 @@ Returns the point as a QPointF.
 
     double distance( double x, double y ) const;
 %Docstring
-Returns the distance between this point and a specified x, y coordinate. In certain
+Returns the Cartesian 2D distance between this point and a specified x, y coordinate. In certain
 cases it may be more appropriate to call the faster distanceSquared() method, e.g.,
 when comparing distances.
 
@@ -218,7 +218,7 @@ when comparing distances.
 
     double distance( const QgsPoint &other ) const;
 %Docstring
-Returns the 2D distance between this point and another point. In certain
+Returns the Cartesian 2D distance between this point and another point. In certain
 cases it may be more appropriate to call the faster distanceSquared() method, e.g.,
 when comparing distances.
 
@@ -227,7 +227,7 @@ when comparing distances.
 
     double distanceSquared( double x, double y ) const;
 %Docstring
-Returns the squared distance between this point a specified x, y coordinate. Calling
+Returns the Cartesian 2D squared distance between this point a specified x, y coordinate. Calling
 this is faster than calling distance(), and may be useful in use cases such as comparing
 distances where the extra expense of calling distance() is not required.
 
@@ -238,7 +238,7 @@ distances where the extra expense of calling distance() is not required.
 
     double distanceSquared( const QgsPoint &other ) const;
 %Docstring
-Returns the squared distance between this point another point. Calling
+Returns the Cartesian 2D squared distance between this point another point. Calling
 this is faster than calling distance(), and may be useful in use cases such as comparing
 distances where the extra expense of calling distance() is not required.
 
@@ -249,7 +249,7 @@ distances where the extra expense of calling distance() is not required.
 
     double distance3D( double x, double y, double z ) const;
 %Docstring
-Returns the 3D distance between this point and a specified x, y, z coordinate. In certain
+Returns the Cartesian 3D distance between this point and a specified x, y, z coordinate. In certain
 cases it may be more appropriate to call the faster distanceSquared() method, e.g.,
 when comparing distances.
 
@@ -260,7 +260,7 @@ when comparing distances.
 
     double distance3D( const QgsPoint &other ) const;
 %Docstring
-Returns the 3D distance between this point and another point. In certain
+Returns the Cartesian 3D distance between this point and another point. In certain
 cases it may be more appropriate to call the faster distanceSquared() method, e.g.,
 when comparing distances.
 
@@ -269,7 +269,7 @@ when comparing distances.
 
     double distanceSquared3D( double x, double y, double z ) const;
 %Docstring
-Returns the 3D squared distance between this point a specified x, y, z coordinate. Calling
+Returns the Cartesian 3D squared distance between this point a specified x, y, z coordinate. Calling
 this is faster than calling distance(), and may be useful in use cases such as comparing
 distances where the extra expense of calling distance() is not required.
 
@@ -280,7 +280,7 @@ distances where the extra expense of calling distance() is not required.
 
     double distanceSquared3D( const QgsPoint &other ) const;
 %Docstring
-Returns the 3D squared distance between this point another point. Calling
+Returns the Cartesian 3D squared distance between this point another point. Calling
 this is faster than calling distance(), and may be useful in use cases such as comparing
 distances where the extra expense of calling distance() is not required.
 
@@ -291,14 +291,14 @@ distances where the extra expense of calling distance() is not required.
 
     double azimuth( const QgsPoint &other ) const;
 %Docstring
-Calculates azimuth between this point and other one (clockwise in degree, starting from north)
+Calculates Cartesian azimuth between this point and other one (clockwise in degree, starting from north)
 
 .. versionadded:: 3.0
 %End
 
     double inclination( const QgsPoint &other ) const;
 %Docstring
-Calculates inclination between this point and other one (starting from zenith = 0 to nadir = 180. Horizon = 90)
+Calculates Cartesian inclination between this point and other one (starting from zenith = 0 to nadir = 180. Horizon = 90)
 Returns 90.0 if the distance between this point and other one is equal to 0 (same point).
 
 .. versionadded:: 3.0
@@ -307,7 +307,7 @@ Returns 90.0 if the distance between this point and other one is equal to 0 (sam
     QgsPoint project( double distance, double azimuth, double inclination = 90.0 ) const;
 %Docstring
 Returns a new point which correspond to this point projected by a specified distance
-with specified angles (azimuth and inclination).
+with specified angles (azimuth and inclination), using Cartesian mathematics.
 M value is preserved.
 
 :param distance: distance to project

src/core/geometry/qgsabstractgeometry.h

@@ -57,6 +57,15 @@ typedef QVector< QVector< QVector< QgsPoint > > > QgsCoordinateSequence;
  * \ingroup core
  * \class QgsAbstractGeometry
  * \brief Abstract base class for all geometries
+ *
+ * \note QgsAbstractGeometry objects are inherently Cartesian/planar geometries. They have no concept of geodesy, and none
+ * of the methods or properties exposed from the QgsAbstractGeometry API (or QgsGeometry API) utilise
+ * geodesic calculations. Accordingly, properties like length() and area() and spatial operations like centroid()
+ * are always calculated using strictly Cartesian mathematics. In contrast, the QgsDistanceArea class exposes
+ * methods for working with geodesic calculations and spatial operations on geometries,
+ * and should be used whenever calculations which account for the curvature of the Earth (or any other celestial body)
+ * are required.
+ *
  * \since QGIS 2.10
  */
 class CORE_EXPORT QgsAbstractGeometry
@@ -419,21 +428,42 @@ class CORE_EXPORT QgsAbstractGeometry
     virtual bool deleteVertex( QgsVertexId position ) = 0;
 
     /**
-     * Returns the length of the geometry.
+     * Returns the planar, 2-dimensional length of the geometry.
+     *
+     * \warning QgsAbstractGeometry objects are inherently Cartesian/planar geometries, and the length
+     * returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+     * the QgsDistanceArea class exposes methods for calculating the lengths of geometries using
+     * geodesic calculations which account for the curvature of the Earth (or any other
+     * celestial body).
+     *
      * \see area()
      * \see perimeter()
      */
     virtual double length() const;
 
     /**
-     * Returns the perimeter of the geometry.
+     * Returns the planar, 2-dimensional perimeter of the geometry.
+     *
+     * \warning QgsAbstractGeometry objects are inherently Cartesian/planar geometries, and the perimeter
+     * returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+     * the QgsDistanceArea class exposes methods for calculating the perimeters of geometries using
+     * geodesic calculations which account for the curvature of the Earth (or any other
+     * celestial body).
+     *
      * \see area()
      * \see length()
      */
     virtual double perimeter() const;
 
     /**
-     * Returns the area of the geometry.
+     * Returns the planar, 2-dimensional area of the geometry.
+     *
+     * \warning QgsAbstractGeometry objects are inherently Cartesian/planar geometries, and the area
+     * returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+     * the QgsDistanceArea class exposes methods for calculating the areas of geometries using
+     * geodesic calculations which account for the curvature of the Earth (or any other
+     * celestial body).
+     *
      * \see length()
      * \see perimeter()
      */
@@ -441,6 +471,10 @@ class CORE_EXPORT QgsAbstractGeometry
 
     /**
      * Returns the length of the segment of the geometry which begins at \a startVertex.
+     *
+     * \warning QgsAbstractGeometry objects are inherently Cartesian/planar geometries, and the lengths
+     * returned by this method are calculated using strictly Cartesian mathematics.
+     *
      * \since QGIS 3.0
      */
     virtual double segmentLength( QgsVertexId startVertex ) const = 0;

src/core/geometry/qgsgeometry.h

@@ -100,14 +100,24 @@ struct QgsGeometryPrivate;
 
 /**
  * \ingroup core
- * A geometry is the spatial representation of a feature. Since QGIS 2.10, QgsGeometry acts as a generic container
- * for geometry objects. QgsGeometry is implicitly shared, so making copies of geometries is inexpensive. The geometry
- * container class can also be stored inside a QVariant object.
+ * A geometry is the spatial representation of a feature.
+ *
+ * QgsGeometry acts as a generic container for geometry objects. QgsGeometry objects are implicitly shared,
+ * so making copies of geometries is inexpensive. The geometry container class can also be stored inside
+ * a QVariant object.
  *
  * The actual geometry representation is stored as a QgsAbstractGeometry within the container, and
- * can be accessed via the get() method or set using the set() method.
+ * can be accessed via the get() method or set using the set() method. This gives access to the underlying
+ * raw geometry primitive, such as the point, line, polygon, curve or other geometry subclasses.
+ *
+ * \note QgsGeometry objects are inherently Cartesian/planar geometries. They have no concept of geodesy, and none
+ * of the methods or properties exposed from the QgsGeometry API (or QgsAbstractGeometry subclasses) utilise
+ * geodesic calculations. Accordingly, properties like length() and area() or spatial operations like buffer()
+ * are always calculated using strictly Cartesian mathematics. In contrast, the QgsDistanceArea class exposes
+ * methods for working with geodesic calculations and spatial operations on geometries,
+ * and should be used whenever calculations which account for the curvature of the Earth (or any other celestial body)
+ * are required.
  */
-
 class CORE_EXPORT QgsGeometry
 {
     Q_GADGET
@@ -377,22 +387,39 @@ class CORE_EXPORT QgsGeometry
     bool isSimple() const;
 
     /**
-     * Returns the area of the geometry using GEOS
+     * Returns the planar, 2-dimensional area of the geometry.
+     *
+     * \warning QgsGeometry objects are inherently Cartesian/planar geometries, and the area
+     * returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+     * the QgsDistanceArea class exposes methods for calculating the areas of geometries using
+     * geodesic calculations which account for the curvature of the Earth (or any other
+     * celestial body).
+     *
+     * \see length()
      * \since QGIS 1.5
      */
     double area() const;
 
     /**
-     * Returns the length of geometry using GEOS
+     * Returns the planar, 2-dimensional length of geometry.
+     *
+     * \warning QgsGeometry objects are inherently Cartesian/planar geometries, and the length
+     * returned by this method is calculated using strictly Cartesian mathematics. In contrast,
+     * the QgsDistanceArea class exposes methods for calculating the lengths of geometries using
+     * geodesic calculations which account for the curvature of the Earth (or any other
+     * celestial body).
+     *
+     * \see area()
      * \since QGIS 1.5
      */
     double length() const;
 
     /**
-     * Returns the minimum distance between this geometry and another geometry, using GEOS.
-     * Will return a negative value if a geometry is missing.
+     * Returns the minimum distance between this geometry and another geometry.
+     * Will return a negative value if either geometry is empty or null.
      *
-     * \param geom geometry to find minimum distance to
+     * \warning QgsGeometry objects are inherently Cartesian/planar geometries, and the distance
+     * returned by this method is calculated using strictly Cartesian mathematics.
      */
     double distance( const QgsGeometry &geom ) const;
 
@@ -611,6 +638,8 @@ class CORE_EXPORT QgsGeometry
      * Returns the distance along this geometry from its first vertex to the specified vertex.
      * \param vertex vertex index to calculate distance to
      * \returns distance to vertex (following geometry), or -1 for invalid vertex numbers
+     * \warning QgsGeometry objects are inherently Cartesian/planar geometries, and the distance
+     * returned by this method is calculated using strictly Cartesian mathematics.
      * \since QGIS 2.16
      */
     double distanceToVertex( int vertex ) const;
@@ -721,6 +750,11 @@ class CORE_EXPORT QgsGeometry
     /**
      * Returns the shortest line joining this geometry to another geometry.
      * \see nearestPoint()
+     *
+     * \warning QgsGeometry objects are inherently Cartesian/planar geometries, and the line
+     * returned by this method is calculated using strictly Cartesian mathematics. See QgsDistanceArea
+     * for similar methods which account for the curvature of an ellipsoidal body such as the Earth.
+     *
      * \since QGIS 2.14
      */
     QgsGeometry shortestLine( const QgsGeometry &other ) const;
@@ -1000,42 +1034,45 @@ class CORE_EXPORT QgsGeometry
      */
     bool boundingBoxIntersects( const QgsGeometry &geometry ) const;
 
-    //! Tests for containment of a point (uses GEOS)
+    /**
+     * Returns TRUE if the geometry contains the point \a p.
+     */
     bool contains( const QgsPointXY *p ) const;
 
     /**
-     * Tests for if geometry is contained in another (uses GEOS)
-     *  \since QGIS 1.5
+     * Returns TRUE if the geometry completely contains another \a geometry.
+     * \since QGIS 1.5
      */
     bool contains( const QgsGeometry &geometry ) const;
 
     /**
-     * Tests for if geometry is disjoint of another (uses GEOS)
-     *  \since QGIS 1.5
+     * Returns TRUE if the geometry is disjoint of another \a geometry.
+     * \since QGIS 1.5
      */
     bool disjoint( const QgsGeometry &geometry ) const;
 
     /**
-     * Test for if geometry touch another (uses GEOS)
-     *  \since QGIS 1.5
+     * Returns TRUE if the geometry touches another \a geometry.
+     * \since QGIS 1.5
      */
     bool touches( const QgsGeometry &geometry ) const;
 
     /**
-     * Test for if geometry overlaps another (uses GEOS)
-     *  \since QGIS 1.5
+     * Returns TRUE if the geometry overlaps another \a geometry.
+     * \since QGIS 1.5
      */
     bool overlaps( const QgsGeometry &geometry ) const;
 
     /**
-     * Test for if geometry is within another (uses GEOS)
-     *  \since QGIS 1.5
+     * Returns TRUE if the geometry is completely within another \a geometry.
+     * \since QGIS 1.5
      */
     bool within( const QgsGeometry &geometry ) const;
 
+
     /**
-     * Test for if geometry crosses another (uses GEOS)
-     *  \since QGIS 1.5
+     * Returns TRUE if the geometry crosses another \a geometry.
+     * \since QGIS 1.5
      */
     bool crosses( const QgsGeometry &geometry ) const;
 

src/core/geometry/qgspoint.h

@@ -296,7 +296,7 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
     }
 
     /**
-     * Returns the distance between this point and a specified x, y coordinate. In certain
+     * Returns the Cartesian 2D distance between this point and a specified x, y coordinate. In certain
      * cases it may be more appropriate to call the faster distanceSquared() method, e.g.,
      * when comparing distances.
      * \see distanceSquared()
@@ -308,7 +308,7 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
     }
 
     /**
-     * Returns the 2D distance between this point and another point. In certain
+     * Returns the Cartesian 2D distance between this point and another point. In certain
      * cases it may be more appropriate to call the faster distanceSquared() method, e.g.,
      * when comparing distances.
      * \since QGIS 3.0
@@ -319,7 +319,7 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
     }
 
     /**
-     * Returns the squared distance between this point a specified x, y coordinate. Calling
+     * Returns the Cartesian 2D squared distance between this point a specified x, y coordinate. Calling
      * this is faster than calling distance(), and may be useful in use cases such as comparing
      * distances where the extra expense of calling distance() is not required.
      * \see distance()
@@ -331,7 +331,7 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
     }
 
     /**
-     * Returns the squared distance between this point another point. Calling
+     * Returns the Cartesian 2D squared distance between this point another point. Calling
      * this is faster than calling distance(), and may be useful in use cases such as comparing
      * distances where the extra expense of calling distance() is not required.
      * \see distance()
@@ -343,7 +343,7 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
     }
 
     /**
-     * Returns the 3D distance between this point and a specified x, y, z coordinate. In certain
+     * Returns the Cartesian 3D distance between this point and a specified x, y, z coordinate. In certain
      * cases it may be more appropriate to call the faster distanceSquared() method, e.g.,
      * when comparing distances.
      * \see distanceSquared()
@@ -352,7 +352,7 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
     double distance3D( double x, double y, double z ) const;
 
     /**
-     * Returns the 3D distance between this point and another point. In certain
+     * Returns the Cartesian 3D distance between this point and another point. In certain
      * cases it may be more appropriate to call the faster distanceSquared() method, e.g.,
      * when comparing distances.
      * \since QGIS 3.0
@@ -360,7 +360,7 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
     double distance3D( const QgsPoint &other ) const;
 
     /**
-     * Returns the 3D squared distance between this point a specified x, y, z coordinate. Calling
+     * Returns the Cartesian 3D squared distance between this point a specified x, y, z coordinate. Calling
      * this is faster than calling distance(), and may be useful in use cases such as comparing
      * distances where the extra expense of calling distance() is not required.
      * \see distance()
@@ -369,7 +369,7 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
     double distanceSquared3D( double x, double y, double z ) const;
 
     /**
-     * Returns the 3D squared distance between this point another point. Calling
+     * Returns the Cartesian 3D squared distance between this point another point. Calling
      * this is faster than calling distance(), and may be useful in use cases such as comparing
      * distances where the extra expense of calling distance() is not required.
      * \see distance()
@@ -378,13 +378,13 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
     double distanceSquared3D( const QgsPoint &other ) const;
 
     /**
-     * Calculates azimuth between this point and other one (clockwise in degree, starting from north)
+     * Calculates Cartesian azimuth between this point and other one (clockwise in degree, starting from north)
      * \since QGIS 3.0
      */
     double azimuth( const QgsPoint &other ) const;
 
     /**
-     * Calculates inclination between this point and other one (starting from zenith = 0 to nadir = 180. Horizon = 90)
+     * Calculates Cartesian inclination between this point and other one (starting from zenith = 0 to nadir = 180. Horizon = 90)
      * Returns 90.0 if the distance between this point and other one is equal to 0 (same point).
      * \since QGIS 3.0
      */
@@ -392,7 +392,7 @@ class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
 
     /**
      * Returns a new point which correspond to this point projected by a specified distance
-     * with specified angles (azimuth and inclination).
+     * with specified angles (azimuth and inclination), using Cartesian mathematics.
      * M value is preserved.
      * \param distance distance to project
      * \param azimuth angle to project in X Y, clockwise in degrees starting from north