Doc: improve Python docstring for RasterBand.ComputeStatistics

doc/source/programs/gdal_translate.rst

@@ -40,8 +40,16 @@ resampling, and rescaling pixels in the process.
 
 .. option:: -strict
 
-    Don't be forgiving of mismatches and lost data when translating to the
-    output format.
+    Enable strict mode. In this mode, GDAL will fail instead of silently
+    performing operations that may lead to loss of information, such as
+    data type conversions that cannot be exactly preserved.
+
+    The exact behavior of this option is driver-dependent. Most raster
+    drivers use it to enforce strict preservation of the input data type
+    and will report an error if the requested operation cannot be performed
+    without data loss. See :example:`strict`.
+
+
 
 .. include:: options/if.rst
 
@@ -443,6 +451,7 @@ This utility is also callable from C with :cpp:func:`GDALTranslate`.
 Examples
 --------
 
+
 .. example::
    :title: Creating a tiled GeoTIFF
 
@@ -474,3 +483,14 @@ Examples
    .. code-block:: bash
 
       gdal_translate -projwin -20037500 10037500 0 0 -outsize 100 100 frmt_wms_googlemaps_tms.xml junk.png
+.. example:: strict
+   :title: Use of strict mode with unsupported data type
+
+   .. code-block:: console
+
+      $ gdal_create test.tif -bands 3 -ot Int16 -outsize 1 1
+      $ gdal_translate -strict test.tif test.webp
+
+      ERROR 6: WEBP driver doesn't support data type Int16.
+      Only Int8 bands supported.
+

swig/include/python/docs/gdal_band_docs.i

@@ -34,29 +34,33 @@ int
 ";
 
 %feature("docstring")  ComputeBandStats "
+Compute statistics for a raster band.
 
-Computes the mean and standard deviation of values in this Band.
-See :cpp:func:`GDALComputeBandStats`.
+This method computes the mean and standard deviation of pixel values
+for the band.
+
+A sampling step can be used to skip rows for faster, approximate
+computation.
 
 Parameters
 ----------
 samplestep : int, default=1
-    Step between scanlines used to compute statistics.
+    Step between scanlines used to compute statistics. A value greater
+    than 1 will result in faster but approximate results.
 
 Returns
 -------
 tuple
-    tuple of length 2 with value of mean and standard deviation
+    A tuple of two values: (mean, std_dev).
 
-See Also
+Examples
 --------
-:py:meth:`ComputeRasterMinMax`
-:py:meth:`ComputeStatistics`
-:py:meth:`GetMaximum`
-:py:meth:`GetMinimum`
-:py:meth:`GetStatistics`
-:py:meth:`SetStatistics`
-";
+>>> from osgeo import gdal
+>>> ds = gdal.Open("example.tif")
+>>> band = ds.GetRasterBand(1)
+>>> mean, std = band.ComputeStatistics(False)
+>>> print(mean, std)
+
 
 %feature("docstring")  CreateMaskBand "