Merge #371

371: Refactoring `vector` module for better maintainability and extensibility. r=lnicola a=metasim

- [X] I agree to follow the project's [code of conduct](https://github.com/georust/gdal/blob/master/CODE_OF_CONDUCT.md).
- [NA] I added an entry to `CHANGES.md` if knowledge of this change could be valuable to users.
---

Refactoring to improve maintainability of vector module.

Changes include:
* Grouping methods of similar purpose into separate files
* Putting associated tests in the same file as the implementation
* Adding or expanding documentation on existing methods
* Normalizing documentation patterns and format.

Intent was to not have any breaking changes.

Co-authored-by: Simeon H.K. Fitch <fitch@astraea.io>

src/dataset.rs

@@ -702,19 +702,19 @@ impl Dataset {
         Ok(self.child_layer(c_layer))
     }
 
-    /// Affine transformation called geotransformation.
+    /// Set the [`Dataset`]'s affine transformation; also called a _geo-transformation_.
     ///
     /// This is like a linear transformation preserves points, straight lines and planes.
     /// Also, sets of parallel lines remain parallel after an affine transformation.
-    /// # Arguments
-    /// * transformation - coeficients of transformations
     ///
-    /// x-coordinate of the top-left corner pixel (x-offset)
-    /// width of a pixel (x-resolution)
-    /// row rotation (typically zero)
-    /// y-coordinate of the top-left corner pixel
-    /// column rotation (typically zero)
-    /// height of a pixel (y-resolution, typically negative)
+    /// # Arguments
+    /// * `transformation` - coefficients of the transformation, which are:
+    ///    - x-coordinate of the top-left corner pixel (x-offset)
+    ///    - width of a pixel (x-resolution)
+    ///    - row rotation (typically zero)
+    ///    - y-coordinate of the top-left corner pixel
+    ///    - column rotation (typically zero)
+    ///    - height of a pixel (y-resolution, typically negative)
     pub fn set_geo_transform(&mut self, transformation: &GeoTransform) -> Result<()> {
         assert_eq!(transformation.len(), 6);
         let rv = unsafe {
@@ -726,14 +726,15 @@ impl Dataset {
         Ok(())
     }
 
-    /// Get affine transformation coefficients.
+    /// Get the coefficients of the [`Dataset`]'s affine transformation.
     ///
-    /// x-coordinate of the top-left corner pixel (x-offset)
-    /// width of a pixel (x-resolution)
-    /// row rotation (typically zero)
-    /// y-coordinate of the top-left corner pixel
-    /// column rotation (typically zero)
-    /// height of a pixel (y-resolution, typically negative)
+    /// # Returns
+    /// - x-coordinate of the top-left corner pixel (x-offset)
+    /// - width of a pixel (x-resolution)
+    /// - row rotation (typically zero)
+    /// - y-coordinate of the top-left corner pixel
+    /// - column rotation (typically zero)
+    /// - height of a pixel (y-resolution, typically negative)
     pub fn geo_transform(&self) -> Result<GeoTransform> {
         let mut transformation = GeoTransform::default();
         let rv =
@@ -833,7 +834,6 @@ impl Dataset {
     /// `None`, which is distinct from an empty [`sql::ResultSet`].
     ///
     /// # Arguments
-    ///
     /// * `query`: The SQL query
     /// * `spatial_filter`: Limit results of the query to features that intersect the given
     ///   [`Geometry`]

src/metadata.rs

@@ -100,8 +100,7 @@ pub trait Metadata: MajorObject {
     /// Entries in the returned `Vec<String>` are formatted as "Name=value" pairs
     ///
     /// # Arguments
-    ///
-    /// * domain – the domain of interest. Use `""` for the default domain.
+    /// * `domain` – the domain of interest. Use `""` for the default domain.
     ///
     /// # Example
     ///

src/raster/mdarray.rs

@@ -233,11 +233,12 @@ impl<'a> MDArray<'a> {
     /// Read a 'Array2<T>' from this band. T implements 'GdalType'.
     ///
     /// # Arguments
-    /// * window - the window position from top left
-    /// * window_size - the window size (GDAL will interpolate data if window_size != array_size)
-    /// * array_size - the desired size of the 'Array'
-    /// * e_resample_alg - the resample algorithm used for the interpolation
-    /// # Docs
+    /// * `window` - the window position from top left
+    /// * `window_size` - the window size (GDAL will interpolate data if window_size != array_size)
+    /// * `array_size` - the desired size of the 'Array'
+    /// * `e_resample_alg` - the resample algorithm used for the interpolation
+    ///
+    /// # Notes
     /// The Matrix shape is (rows, cols) and raster shape is (cols in x-axis, rows in y-axis).
     pub fn read_as_array<T: Copy + GdalType + Debug>(
         &self,

src/raster/rasterband.rs

@@ -225,7 +225,6 @@ impl<'a> RasterBand<'a> {
     /// Read data from this band into a slice, where `T` implements [`GdalType`]
     ///
     /// # Arguments
-    ///
     /// * `window` - the window position from top left
     /// * `window_size` - the window size (GDAL will interpolate data if window_size != buffer_size)
     /// * `size` - the desired size to read
@@ -296,7 +295,6 @@ impl<'a> RasterBand<'a> {
     /// Read a [`Buffer<T>`] from this band, where `T` implements [`GdalType`].
     ///
     /// # Arguments
-    ///
     /// * `window` - the window position from top left
     /// * `window_size` - the window size (GDAL will interpolate data if `window_size` != `buffer_size`)
     /// * `buffer_size` - the desired size of the 'Buffer'
@@ -376,7 +374,6 @@ impl<'a> RasterBand<'a> {
     /// Read a [`Array2<T>`] from this band, where `T` implements [`GdalType`].
     ///
     /// # Arguments
-    ///
     /// * `window` - the window position from top left
     /// * `window_size` - the window size (GDAL will interpolate data if window_size != array_size)
     /// * `array_size` - the desired size of the 'Array'
@@ -413,7 +410,7 @@ impl<'a> RasterBand<'a> {
     /// # Arguments
     /// * `block_index` - the block index
     ///
-    /// # Note
+    /// # Notes
     /// The Matrix shape is (rows, cols) and raster shape is (cols in x-axis, rows in y-axis).
     pub fn read_block<T: Copy + GdalType>(&self, block_index: (usize, usize)) -> Result<Array2<T>> {
         let size = self.block_size();
@@ -443,7 +440,6 @@ impl<'a> RasterBand<'a> {
     /// Write a [`Buffer<T>`] into a [`Dataset`].
     ///
     /// # Arguments
-    ///
     /// * `window` - the window position from top left
     /// * `window_size` - the window size (GDAL will interpolate data if window_size != Buffer.size)
     /// * `buffer` - the data to write into the window

src/spatial_ref/srs.rs

@@ -37,14 +37,14 @@ impl CoordTransform {
     /// transformations.
     ///
     /// # Arguments
-    /// * bounds - array of [axis0_min, axis1_min, axis0_max, axis1_min],
+    /// * `bounds` - array of [axis0_min, axis1_min, axis0_max, axis1_min],
     ///            interpreted in the axis order of the source SpatialRef,
     ///            typically [xmin, ymin, xmax, ymax]
-    /// * densify_pts - number of points per edge (recommended: 21)
+    /// * `densify_pts` - number of points per edge (recommended: 21)
     ///
     /// # Returns
-    /// Some([f64; 4]) with bounds in axis order of target SpatialRef
-    /// None if there is an error.
+    /// `Ok([f64; 4])` with bounds in axis order of target SpatialRef
+    /// `Err` if there is an error.
     #[cfg(all(major_ge_3, minor_ge_4))]
     pub fn transform_bounds(&self, bounds: &[f64; 4], densify_pts: i32) -> Result<[f64; 4]> {
         let mut out_xmin: f64 = 0.;
@@ -88,9 +88,9 @@ impl CoordTransform {
     /// Transform coordinates in place.
     ///
     /// # Arguments
-    /// * x - slice of x coordinates
-    /// * y - slice of y coordinates (must match x in length)
-    /// * z - slice of z coordinates, or an empty slice to ignore
+    /// * `x` - slice of x coordinates
+    /// * `y` - slice of y coordinates (must match x in length)
+    /// * `z` - slice of z coordinates, or an empty slice to ignore
     pub fn transform_coords(&self, x: &mut [f64], y: &mut [f64], z: &mut [f64]) -> Result<()> {
         let nb_coords = x.len();
         assert_eq!(