From b73a9643be0c4c62c13e5f9b2a546ded5fb177d7 Mon Sep 17 00:00:00 2001
From: Even Rouault <even.rouault@spatialys.com>
Date: Fri, 7 Feb 2025 15:38:35 +0100
Subject: [PATCH] Doc: specify what happens for Z/M for AddPoint() /
 AddPoint_2D()

Fixes #11818
---
 ogr/ogr_api.cpp                              | 21 ++++++++++
 swig/include/python/docs/ogr_geometry_docs.i | 42 ++++++++++++++++++++
 2 files changed, 63 insertions(+)

diff --git a/ogr/ogr_api.cpp b/ogr/ogr_api.cpp
index bfb482a75453..8bb6a5daaef2 100644
--- a/ogr/ogr_api.cpp
+++ b/ogr/ogr_api.cpp
@@ -872,6 +872,9 @@ void CPL_DLL OGR_G_SetPointsZM(OGRGeometryH hGeom, int nPointsIn,
  * points in the linestring, the point count will be increased to
  * accommodate the request.
  *
+ * The geometry is promoted to include a Z component, if it does not already
+ * have one.
+ *
  * @param hGeom handle to the geometry to add a vertex to.
  * @param i the index of the vertex to assign (zero based) or
  *  zero for a point.
@@ -993,6 +996,9 @@ void OGR_G_SetPoint_2D(OGRGeometryH hGeom, int i, double dfX, double dfY)
  * points in the linestring, the point count will be increased to
  * accommodate the request.
  *
+ * The geometry is promoted to include a M component, if it does not already
+ * have one.
+ *
  * @param hGeom handle to the geometry to add a vertex to.
  * @param i the index of the vertex to assign (zero based) or
  *  zero for a point.
@@ -1055,6 +1061,9 @@ void OGR_G_SetPointM(OGRGeometryH hGeom, int i, double dfX, double dfY,
  * points in the linestring, the point count will be increased to
  * accommodate the request.
  *
+ * The geometry is promoted to include a Z and M component, if it does not
+ * already have them.
+ *
  * @param hGeom handle to the geometry to add a vertex to.
  * @param i the index of the vertex to assign (zero based) or
  *  zero for a point.
@@ -1118,6 +1127,9 @@ void OGR_G_SetPointZM(OGRGeometryH hGeom, int i, double dfX, double dfY,
  * The vertex count of the line string is increased by one, and assigned from
  * the passed location value.
  *
+ * The geometry is promoted to include a Z component, if it does not already
+ * have one.
+ *
  * @param hGeom handle to the geometry to add a point to.
  * @param dfX x coordinate of point to add.
  * @param dfY y coordinate of point to add.
@@ -1161,6 +1173,9 @@ void OGR_G_AddPoint(OGRGeometryH hGeom, double dfX, double dfY, double dfZ)
  * The vertex count of the line string is increased by one, and assigned from
  * the passed location value.
  *
+ * If the geometry includes a Z or M component, the value for those components
+ * for the added point will be 0.
+ *
  * @param hGeom handle to the geometry to add a point to.
  * @param dfX x coordinate of point to add.
  * @param dfY y coordinate of point to add.
@@ -1202,6 +1217,9 @@ void OGR_G_AddPoint_2D(OGRGeometryH hGeom, double dfX, double dfY)
  * The vertex count of the line string is increased by one, and assigned from
  * the passed location value.
  *
+ * The geometry is promoted to include a M component, if it does not already
+ * have one.
+ *
  * @param hGeom handle to the geometry to add a point to.
  * @param dfX x coordinate of point to add.
  * @param dfY y coordinate of point to add.
@@ -1245,6 +1263,9 @@ void OGR_G_AddPointM(OGRGeometryH hGeom, double dfX, double dfY, double dfM)
  * The vertex count of the line string is increased by one, and assigned from
  * the passed location value.
  *
+ * The geometry is promoted to include a Z and M component, if it does not
+ * already have them.
+ *
  * @param hGeom handle to the geometry to add a point to.
  * @param dfX x coordinate of point to add.
  * @param dfY y coordinate of point to add.
diff --git a/swig/include/python/docs/ogr_geometry_docs.i b/swig/include/python/docs/ogr_geometry_docs.i
index c5c923b67571..472c4fc6728a 100644
--- a/swig/include/python/docs/ogr_geometry_docs.i
+++ b/swig/include/python/docs/ogr_geometry_docs.i
@@ -894,4 +894,46 @@ For more details: :cpp:func:`OGR_G_SwapXY`
 
 ";
 
+
+%feature("docstring")  AddPoint "
+Add a point to a geometry (line string or point).
+
+The vertex count of the line string is increased by one, and assigned from
+the passed location value.
+
+The geometry is promoted to include a Z component, if it does not already
+have one, even if the Z parameter is not explicitly specified. To avoid that
+use AddPoint_2D.
+
+This is the same as :cpp:func:`OGR_G_AddPoint`
+
+Parameters
+-----------
+X: float
+    x coordinate of point to add.
+Y: float
+    y coordinate of point to add.
+Z: float
+    z coordinate of point to add. Defaults to 0
+";
+
+%feature("docstring")  AddPoint_2D "
+Add a point to a geometry (line string or point).
+
+The vertex count of the line string is increased by one, and assigned from
+the passed location value.
+
+If the geometry includes a Z or M component, the value for those components
+for the added point will be 0.
+
+This is the same as :cpp:func:`OGR_G_AddPoint_2D`
+
+Parameters
+-----------
+X: float
+    x coordinate of point to add.
+Y: float
+    y coordinate of point to add.
+";
+
 }