Doc: specify what happens for Z/M for AddPoint() / AddPoint_2D()

Fixes OSGeo#11818

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.

swig/include/python/docs/ogr_geometry_docs.i

@@ -894,4 +894,63 @@ 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
+
+Examples
+-------
+>>> ogr.GeometryTypeToName(pt.GetGeometryType())
+'Point'
+>>> pt.AddPoint(3, 7)
+>>> ogr.GeometryTypeToName(pt.GetGeometryType())
+'3D Point'
+";
+
+%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.
+
+Examples
+--------
+>>> pt = ogr.Geometry(ogr.wkbPoint)
+>>> ogr.GeometryTypeToName(pt.GetGeometryType())
+'Point'
+>>> pt.AddPoint_2D(3, 7)
+>>> ogr.GeometryTypeToName(pt.GetGeometryType())
+'Point'
+";
+
 }