docs(sedona-gdal): tighten wrapper API comments

Author: Kontinuation

c/sedona-gdal/src/dataset.rs

@@ -146,7 +146,8 @@ impl Dataset {
         unsafe { call_gdal_api!(self.api, GDALGetRasterCount, self.c_dataset) as usize }
     }
 
-    /// Get a raster band (1-indexed).
+    /// Fetch a raster band by 1-indexed band number.
+    /// Band numbers start at 1, as in GDAL.
     pub fn rasterband(&self, band_index: usize) -> Result<RasterBand<'_>> {
         let band_index_i32 = i32::try_from(band_index)?;
         let c_band =
@@ -157,7 +158,8 @@ impl Dataset {
         Ok(RasterBand::new(self.api, c_band, self))
     }
 
-    /// Get the geo-transform.
+    /// Fetch the dataset geotransform coefficients.
+    /// Return an error if no geotransform is available.
     pub fn geo_transform(&self) -> Result<[f64; 6]> {
         let mut gt = [0.0f64; 6];
         let rv = unsafe {
@@ -190,7 +192,8 @@ impl Dataset {
         Ok(())
     }
 
-    /// Get the projection string.
+    /// Fetch the projection definition string for this dataset.
+    /// Return an empty string if no projection is available.
     pub fn projection(&self) -> String {
         unsafe {
             let ptr = call_gdal_api!(self.api, GDALGetProjectionRef, self.c_dataset);
@@ -202,7 +205,7 @@ impl Dataset {
         }
     }
 
-    /// Set the projection string.
+    /// Set the projection definition string for this dataset.
     pub fn set_projection(&self, projection: &str) -> Result<()> {
         let c_projection = CString::new(projection)?;
         let rv = unsafe {
@@ -219,7 +222,8 @@ impl Dataset {
         Ok(())
     }
 
-    /// Get the spatial reference.
+    /// Fetch the spatial reference for this dataset.
+    /// GDAL returns a borrowed handle; this method clones it.
     pub fn spatial_ref(&self) -> Result<SpatialRef> {
         let c_srs = unsafe { call_gdal_api!(self.api, GDALGetSpatialRef, self.c_dataset) };
         if c_srs.is_null() {
@@ -317,24 +321,12 @@ impl Dataset {
         )
     }
 
-    /// Add a raster band backed by an existing memory buffer (zero-copy).
-    ///
-    /// This wraps `GDALAddBand` with the `DATAPOINTER`, `PIXELOFFSET`, and `LINEOFFSET`
-    /// options, allowing you to attach existing memory to a MEM dataset without copying.
-    ///
-    /// # Arguments
-    /// * `data_type` - The GDAL data type of the band.
-    /// * `data_ptr` - Pointer to the band pixel data.
-    /// * `pixel_offset` - Byte offset between consecutive pixels. `None` defaults to the
-    ///   byte size of `data_type`.
-    /// * `line_offset` - Byte offset between consecutive lines. `None` defaults to
-    ///   `pixel_offset * width`.
+    /// Add a band backed by an existing memory buffer.
+    /// Pass `DATAPOINTER`, `PIXELOFFSET`, and `LINEOFFSET` to `GDALAddBand`.
     ///
     /// # Safety
     ///
-    /// The caller must ensure that `data_ptr` points to a valid buffer of at least
-    /// `height * line_offset` bytes (or `height * width * data_type.byte_size()` when
-    /// using defaults), and that the buffer outlives this dataset.
+    /// `data_ptr` must point to valid band data that outlives this dataset.
     pub unsafe fn add_band_with_data(
         &self,
         data_type: RustGdalDataType,

c/sedona-gdal/src/raster/rasterband.rs

@@ -52,9 +52,8 @@ impl<'a> RasterBand<'a> {
         self.c_rasterband
     }
 
-    /// Read a region of the band as a typed buffer.
-    ///
-    /// If `e_resample_alg` is `None`, nearest-neighbour resampling is used.
+    /// Read a window of this band into a typed buffer.
+    /// If `e_resample_alg` is `None`, use nearest-neighbour resampling.
     pub fn read_as<T: GdalType + Copy>(
         &self,
         window: (isize, isize),
@@ -137,24 +136,24 @@ impl<'a> RasterBand<'a> {
         Ok(())
     }
 
-    /// Get the data type of this band.
+    /// Fetch this band's data type.
     pub fn band_type(&self) -> GdalDataType {
         GdalDataType::from_c(self.c_band_type()).unwrap_or(GdalDataType::Unknown)
     }
 
-    /// Get the GDAL data type of this band.
+    /// Fetch this band's raw GDAL data type.
     pub fn c_band_type(&self) -> GDALDataType {
         unsafe { call_gdal_api!(self.api, GDALGetRasterDataType, self.c_rasterband) }
     }
 
-    /// Get band size as (x_size, y_size).
+    /// Fetch band size as `(x_size, y_size)`.
     pub fn size(&self) -> (usize, usize) {
         let x = unsafe { call_gdal_api!(self.api, GDALGetRasterBandXSize, self.c_rasterband) };
         let y = unsafe { call_gdal_api!(self.api, GDALGetRasterBandYSize, self.c_rasterband) };
         (x as usize, y as usize)
     }
 
-    /// Get the block size as (x_size, y_size).
+    /// Fetch the natural block size as `(x_size, y_size)`.
     pub fn block_size(&self) -> (usize, usize) {
         let mut x: i32 = 0;
         let mut y: i32 = 0;
@@ -170,7 +169,8 @@ impl<'a> RasterBand<'a> {
         (x as usize, y as usize)
     }
 
-    /// Get the no-data value. Returns `Some(value)` if set, `None` otherwise.
+    /// Fetch the band's nodata value.
+    /// Return `None` if no nodata value is set.
     pub fn no_data_value(&self) -> Option<f64> {
         let mut success: i32 = 0;
         let value = unsafe {
@@ -188,7 +188,8 @@ impl<'a> RasterBand<'a> {
         }
     }
 
-    /// Set or clear the no-data value.
+    /// Set the band's nodata value.
+    /// Pass `None` to clear any existing nodata value.
     pub fn set_no_data_value(&self, value: Option<f64>) -> Result<()> {
         let rv = if let Some(val) = value {
             unsafe { call_gdal_api!(self.api, GDALSetRasterNoDataValue, self.c_rasterband, val) }
@@ -201,7 +202,8 @@ impl<'a> RasterBand<'a> {
         Ok(())
     }
 
-    /// Set or clear the no-data value as u64.
+    /// Set the band's nodata value as `u64`.
+    /// Pass `None` to clear any existing nodata value.
     pub fn set_no_data_value_u64(&self, value: Option<u64>) -> Result<()> {
         let rv = if let Some(val) = value {
             unsafe {
@@ -221,7 +223,8 @@ impl<'a> RasterBand<'a> {
         Ok(())
     }
 
-    /// Set or clear the no-data value as i64.
+    /// Set the band's nodata value as `i64`.
+    /// Pass `None` to clear any existing nodata value.
     pub fn set_no_data_value_i64(&self, value: Option<i64>) -> Result<()> {
         let rv = if let Some(val) = value {
             unsafe {
@@ -247,7 +250,8 @@ impl<'a> RasterBand<'a> {
     }
 }
 
-/// Compute the actual block size (clamped to raster extent) for a given block index.
+/// Return the actual block size for a block index.
+/// Clamp edge blocks to the raster extent.
 pub fn actual_block_size(
     band: &RasterBand<'_>,
     block_index: (usize, usize),

c/sedona-gdal/src/vector/feature.rs

@@ -51,9 +51,8 @@ impl<'a> Feature<'a> {
         }
     }
 
-    /// Get the geometry reference (borrowed, not owned — do not destroy).
-    ///
-    /// Returns None if the feature has no geometry.
+    /// Fetch the feature geometry.
+    /// The returned geometry is borrowed; return `None` if no geometry is set.
     pub fn geometry(&self) -> Option<BorrowedGeometry<'_>> {
         let c_geom = unsafe { call_gdal_api!(self.api, OGR_F_GetGeometryRef, self.c_feature) };
         if c_geom.is_null() {
@@ -67,7 +66,8 @@ impl<'a> Feature<'a> {
         }
     }
 
-    /// Get a field's index by name. Returns an error if the field is not found.
+    /// Fetch the index of a field by name.
+    /// Return an error if the field is not found.
     pub fn field_index(&self, name: &str) -> Result<i32> {
         let c_name = CString::new(name)?;
         let idx = unsafe {
@@ -84,7 +84,7 @@ impl<'a> Feature<'a> {
         Ok(idx)
     }
 
-    /// Get a field value as f64.
+    /// Fetch a field value as `f64`.
     pub fn field_as_double(&self, field_index: i32) -> f64 {
         unsafe {
             call_gdal_api!(
@@ -96,9 +96,8 @@ impl<'a> Feature<'a> {
         }
     }
 
-    /// Get a field value as i32.
-    ///
-    /// Returns `Some(value)` if the field is set and not null, `None` otherwise.
+    /// Fetch a field value as `i32`.
+    /// Return `None` if the field is unset or null.
     pub fn field_as_integer(&self, field_index: i32) -> Option<i32> {
         let is_set = unsafe {
             call_gdal_api!(
@@ -163,7 +162,7 @@ impl<'a> BorrowedGeometry<'a> {
         Ok(buf)
     }
 
-    /// Get the bounding envelope.
+    /// Fetch the 2D envelope of this geometry.
     pub fn envelope(&self) -> Envelope {
         let mut env = OGREnvelope {
             MinX: 0.0,

c/sedona-gdal/src/vector/layer.rs

@@ -53,7 +53,8 @@ impl<'a> Layer<'a> {
         unsafe { call_gdal_api!(self.api, OGR_L_ResetReading, self.c_layer) };
     }
 
-    /// Get the next feature (returns None when exhausted).
+    /// Fetch the next feature from the current read cursor.
+    /// Return `None` when no more features are available.
     pub fn next_feature(&self) -> Option<Feature<'_>> {
         let c_feature = unsafe { call_gdal_api!(self.api, OGR_L_GetNextFeature, self.c_layer) };
         if c_feature.is_null() {
@@ -63,7 +64,8 @@ impl<'a> Layer<'a> {
         }
     }
 
-    /// Create a field on this layer.
+    /// Create a field in this layer.
+    /// Allow the driver to approximate the definition if needed.
     pub fn create_field(&self, field_defn: &FieldDefn) -> Result<()> {
         let rv = unsafe {
             call_gdal_api!(
@@ -83,9 +85,8 @@ impl<'a> Layer<'a> {
         Ok(())
     }
 
-    /// Get the number of features in this layer.
-    ///
-    /// If `force` is true, the count will be computed even if it is expensive.
+    /// Fetch the feature count for this layer.
+    /// Return `-1` if the count is unknown and `force` is `false`.
     pub fn feature_count(&self, force: bool) -> i64 {
         unsafe {
             call_gdal_api!(
@@ -97,7 +98,8 @@ impl<'a> Layer<'a> {
         }
     }
 
-    /// Iterate over all features.
+    /// Iterate over features from the start of the layer.
+    /// This resets the layer read cursor before iteration.
     pub fn features(&mut self) -> FeatureIterator<'_> {
         self.reset_reading();
         FeatureIterator { layer: self }