update api and doc comments

Author: espdev

src/ndg.rs

@@ -19,7 +19,7 @@ use crate::Result;
 
 /// N-d grid spline PP-form representation
 ///
-/// `NdGridSpline` represents n-dimensional splines for n-d grid data. In n-d grid case
+/// `NdGridSpline` represents n-dimensional splines for n-dimensional grid data. In n-d grid case
 /// the spline is represented as tensor-product of univariate spline coefficients along every
 /// diemnsion.
 ///
@@ -55,6 +55,16 @@ impl<'a, T, D> NdGridSpline<'a, T, D>
         T: NdFloat + AlmostEqual,
         D: Dimension
 {
+    /// Creates `NdGridSpline` struct from given `breaks` and `coeffs`
+    ///
+    /// # Arguments
+    ///
+    /// - `breaks` -- The vector of the breaks (data sites) which have been used for computing spline
+    /// - `coeffs` -- The n-d array of tensor-product spline coefficients
+    ///
+    /// # Notes
+    ///
+    /// - `NdGridSpline` struct should not be created directly by a user in most cases.
     ///
     pub fn new(breaks: Vec<ArrayView1<'a, T>>, coeffs: Array<T, D>) -> Self {
         let ndim = breaks.len();
@@ -70,7 +80,7 @@ impl<'a, T, D> NdGridSpline<'a, T, D>
         }
     }
 
-    /// Returns the spline dimensionality
+    /// Returns the n-d grid spline dimensionality
     pub fn ndim(&self) -> usize { self.ndim }
 
     /// Returns the vector of the spline order for each dimension
@@ -94,12 +104,35 @@ impl<'a, T, D> NdGridSpline<'a, T, D>
 
 /// N-dimensional grid cubic smoothing spline calculator/evaluator
 ///
-/// The struct represents n-d grid smoothing cubic spline and allows you to make and evaluate the
-/// splines for given n-d grid data.
+/// The struct represents n-dimensional grid smoothing cubic spline and allows you to make
+/// and evaluate the splines for given n-dimensional grid data.
 ///
-/// `CubicSmoothingSpline` struct is parametrized by data type (`f64` or `f32`)
+/// `GridCubicSmoothingSpline` struct is parametrized by data type (`f64` or `f32`)
 /// and data dimension.
 ///
+/// The methods API of `GridCubicSmoothingSpline` is implemented as builder-like pattern or in other
+/// words as chained API (also as `CubicSmoothingSpline` struct):
+///
+/// ```
+/// use ndarray::array;
+/// use csaps::GridCubicSmoothingSpline;
+///
+/// let x0 = array![1.0, 2.0, 3.0, 4.0];
+/// let x1 = array![1.0, 2.0, 3.0, 4.0];
+/// let x = vec![x0.view(), x1.view()];
+///
+/// let y = vec![
+///     [0.5, 1.2, 3.4, 2.5],
+///     [1.5, 2.2, 4.4, 3.5],
+///     [2.5, 3.2, 5.4, 4.5],
+///     [3.5, 4.2, 6.4, 5.5],
+/// ];
+///
+/// let ys = GridCubicSmoothingSpline::new(&x, &y)
+///     .make().unwrap()
+///     .evaluate(&x).unwrap();
+/// ```
+///
 pub struct GridCubicSmoothingSpline<'a, T, D>
     where
         T: NdFloat,
@@ -117,7 +150,7 @@ pub struct GridCubicSmoothingSpline<'a, T, D>
     /// The optional smoothing parameter
     smooth: Vec<Option<T>>,
 
-    /// `NdSpline` struct with computed spline
+    /// `NdGridSpline` struct with computed spline
     spline: Option<NdGridSpline<'a, T, D>>
 }
 
@@ -128,6 +161,13 @@ impl<'a, T, D> GridCubicSmoothingSpline<'a, T, D>
         D: Dimension
 {
     /// Creates `NdGridCubicSmoothingSpline` struct from the given `X` data sites and `Y` data values
+    ///
+    /// # Arguments
+    ///
+    /// - `x` -- the slice of X-data sites 1-d array view for each dimension.
+    ///   Each data sites must strictly increasing: `x1 < x2 < x3 < ... < xN`.
+    /// - `y` -- The Y-data n-d grid values array-like. `ndim` can be from 1 to N.
+    ///
     pub fn new<Y>(x: &[ArrayView1<'a, T>], y: Y) -> Self
         where
             Y: AsArray<'a, T, D>
@@ -143,19 +183,31 @@ impl<'a, T, D> GridCubicSmoothingSpline<'a, T, D>
         }
     }
 
-    /// Sets the data weights
+    /// Sets the weights data vectors for each dimension
     ///
-    /// `weights.len()` must be equal to `x.len()`
+    /// # Arguments
+    ///
+    /// - `weights` -- the slice of optional weights arrays (array-like) for each dimension
+    ///
+    /// # Notes
+    ///
+    /// `weights` vectors sizes must be equal to `x` data site sizes for each dimension.
     ///
     pub fn with_weights(mut self, weights: &[Option<ArrayView1<'a, T>>]) -> Self {
         self.invalidate();
         self.weights = weights.to_vec();
         self
     }
 
-    /// Sets the smoothing parameters for each axis
+    /// Sets the smoothing parameters for each dimension
+    ///
+    /// # Arguments
     ///
-    /// The smoothing parameters should be in range `[0, 1]`,
+    /// - `smooth` - the slice of optional smoothing parameters for each dimension
+    ///
+    /// # Notes
+    ///
+    /// The smoothing parameters should be in range `[0, 1]` or `None`,
     /// where bounds are:
     ///
     ///  - 0: The smoothing spline is the least-squares straight line fit to the data
@@ -169,7 +221,27 @@ impl<'a, T, D> GridCubicSmoothingSpline<'a, T, D>
         self
     }
 
-    /// Makes (computes) the n-d grid spline for given data and parameters
+    /// Sets the smoothing parameter for all dimensions
+    ///
+    /// # Arguments
+    ///
+    /// - `smooth` - the smoothing parameter value that the same for all dimensions
+    ///
+    /// # Notes
+    ///
+    /// The smoothing parameter should be in range `[0, 1]`,
+    /// where bounds are:
+    ///
+    ///  - 0: The smoothing spline is the least-squares straight line fit to the data
+    ///  - 1: The cubic spline interpolant with natural boundary condition
+    ///
+    pub fn with_all_smooth(mut self, smooth: T) -> Self {
+        self.invalidate();
+        self.smooth = vec![Some(smooth); self.x.len()];
+        self
+    }
+
+    /// Makes (computes) the n-dimensional grid spline for given data and parameters
     ///
     /// # Errors
     ///
@@ -183,7 +255,7 @@ impl<'a, T, D> GridCubicSmoothingSpline<'a, T, D>
         Ok(self)
     }
 
-    /// Evaluates the computed n-d grid spline on the given data sites
+    /// Evaluates the computed n-dimensional grid spline on the given data sites
     ///
     /// # Errors
     ///

src/umv.rs

@@ -53,12 +53,12 @@ impl<'a, T> NdSpline<'a, T>
 {
     /// Creates `NdSpline` struct from given `breaks` and `coeffs`
     ///
-    /// Arguments:
+    /// # Arguments
     ///
     /// - `breaks` -- The breaks (data sites) which have been used for computing spline
     /// - `coeffs` -- The NxM array of spline coefficients where N is `ndim` and M is row of pieces of coefficients
     ///
-    /// Note:
+    /// # Notes
     ///
     /// - `NdSpline` struct should not be created directly by a user in most cases.
     ///
@@ -113,7 +113,7 @@ impl<'a, T> NdSpline<'a, T>
 /// `CubicSmoothingSpline` struct is parametrized by data type (`f64` or `f32`)
 /// and data dimension.
 ///
-/// The methods API of `CubicSmoothingSpline` is implemented as "builder" pattern or in other
+/// The methods API of `CubicSmoothingSpline` is implemented as builder-loke pattern or in other
 /// words as chained API:
 ///
 /// ```
@@ -173,7 +173,7 @@ impl<'a, T, D> CubicSmoothingSpline<'a, T, D>
 {
     /// Creates `CubicSmoothingSpline` struct from the given `X` data sites and `Y` data values
     ///
-    /// Arguments:
+    /// # Arguments
     ///
     /// - `x` -- the X-data sites 1-d array-like. Must strictly increasing: x1 < x2 < x3 < ... < xN
     /// - `y` -- The Y-data values n-d array-like. `ndim` can be from 1 to N. The splines will be computed for