From 0354358b0a5d054d12697c4526cc8b0d446ca00d Mon Sep 17 00:00:00 2001
From: Dan Baston <dbaston@gmail.com>
Date: Tue, 4 Feb 2025 11:13:31 -0500
Subject: [PATCH] gdalrasterize.cpp: Add docstring to gv_rasterize_one_shape

---
 alg/gdalrasterize.cpp | 43 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 36 insertions(+), 7 deletions(-)

diff --git a/alg/gdalrasterize.cpp b/alg/gdalrasterize.cpp
index 46d7a3c0646a..d5a0ac45ce96 100644
--- a/alg/gdalrasterize.cpp
+++ b/alg/gdalrasterize.cpp
@@ -539,9 +539,35 @@ static void GDALCollectRingsFromGeometry(const OGRGeometry *poShape,
     }
 }
 
-/************************************************************************/
-/*                       gv_rasterize_one_shape()                       */
-/************************************************************************/
+/************************************************************************
+ *                       gv_rasterize_one_shape()
+ *
+ * @param pabyChunkBuf buffer to which values will be burned
+ * @param nXOff chunk column offset from left edge of raster
+ * @param nYOff chunk scanline offset from top of raster
+ * @param nXSize number of columns in chunk
+ * @param nYSize number of rows in chunk
+ * @param nBands number of bands in chunk
+ * @param eType data type of pabyChunkBuf
+ * @param nPixelSpace number of bytes between adjacent pixels in chunk
+ *                    (0 to calculate automatically)
+ * @param nLineSpace number of bytes between adjacent scanlines in chunk
+ *                   (0 to calculate automatically)
+ * @param nBandSpace number of bytes between adjacent bands in chunk
+ *                   (0 to calculate automatically)
+ * @param bAllTouched burn value to all touched pixels?
+ * @param poShape geometry to rasterize, in original coordinates
+ * @param eBurnValueType type of value to be burned (must be Float64 or Int64)
+ * @param padfBurnValues array of nBands values to burn (Float64), or nullptr
+ * @param panBurnValues array of nBands values to burn (Int64), or nullptr
+ * @param eBurnValueSrc whether to burn values from padfBurnValues /
+ *                      panBurnValues, or from the Z or M values of poShape
+ * @param eMergeAlg whether the burn value should replace or be added to the
+ *                  existing values
+ * @param pfnTransformer transformer from CRS of geometry to pixel/line
+ *                       coordinates of raster
+ * @param pTransformArg arguments to pass to pfnTransformer
+ ************************************************************************/
 static void gv_rasterize_one_shape(
     unsigned char *pabyChunkBuf, int nXOff, int nYOff, int nXSize, int nYSize,
     int nBands, GDALDataType eType, int nPixelSpace, GSpacing nLineSpace,
@@ -614,10 +640,13 @@ static void gv_rasterize_one_shape(
     /*      Transform polygon geometries into a set of rings and a part     */
     /*      size list.                                                      */
     /* -------------------------------------------------------------------- */
-    std::vector<double> aPointX;
-    std::vector<double> aPointY;
-    std::vector<double> aPointVariant;
-    std::vector<int> aPartSize;
+    std::vector<double>
+        aPointX;  // coordinate X values from all rings/components
+    std::vector<double>
+        aPointY;  // coordinate Y values from all rings/components
+    std::vector<double> aPointVariant;  // coordinate Z values
+    std::vector<int> aPartSize;  // number of X/Y/(Z) values associated with
+                                 // each ring/component
 
     GDALCollectRingsFromGeometry(poShape, aPointX, aPointY, aPointVariant,
                                  aPartSize, eBurnValueSrc);