[Improvement] General revision of functions, classes and public methods documentation

asltk/asldata.py

@@ -134,9 +134,9 @@ def __init__(
         logger.debug('ASLData object created successfully')
 
     def set_image(self, image, spec: str):
-        """Insert a image necessary to define de ASL data processing.
+        """Insert an image necessary to define the ASL data processing.
 
-        The `spec` parameters specifies what is the type of image to be used in
+        The `spec` parameter specifies what is the type of image to be used in
         ASL processing step. Choose one of the options: `m0` for the M0 volume,
         `pcasl` for the pCASL data.
 
@@ -333,3 +333,19 @@ def _check_m0_dimension(self):
                 'This may cause issues in processing. '
                 'Consider averaging the M0 image across the first dimension.'
             )
+
+    def _check_m0_dimension(self):
+        if len(self._m0_image.shape) > 3:
+            warnings.warn(
+                'M0 image has more than 3 dimensions. '
+                'This may cause issues in processing. '
+                'Consider averaging the M0 image across the first dimension.'
+            )
+
+    def _check_m0_dimension(self):
+        if len(self._m0_image.shape) > 3:
+            warnings.warn(
+                'M0 image has more than 3 dimensions. '
+                'This may cause issues in processing. '
+                'Consider averaging the M0 image across the first dimension.'
+            )

asltk/aux_methods.py

@@ -7,6 +7,24 @@
 
 
 def _check_mask_values(mask, label, ref_shape):
+    """Validate mask array for brain mask processing.
+
+    This function performs comprehensive validation of brain mask data to ensure
+    it meets the requirements for ASL processing. It checks data type, binary
+    format compliance, label presence, and dimensional compatibility.
+
+    Args:
+        mask (np.ndarray): The brain mask image to validate.
+        label (int or float): The label value to search for in the mask.
+        ref_shape (tuple): The reference shape that the mask should match.
+
+    Raises:
+        TypeError: If mask is not a numpy array or dimensions don't match.
+        ValueError: If the specified label value is not found in the mask.
+
+    Warnings:
+        UserWarning: If mask contains more than 2 unique values (not strictly binary).
+    """
     # Check wheter mask input is an numpy array
     if not isinstance(mask, np.ndarray):
         raise TypeError(f'mask is not an numpy array. Type {type(mask)}')

asltk/models/signal_dynamic.py

@@ -18,8 +18,8 @@ def asl_model_buxton(
     It is assumed that the LD and PLD values are coherent with the ASl Buxton
     model, i.e. the both has the same array size.
 
-    The calculations is given assuming a voxel value. Hence, all the `tau`,
-    `w`, `cbf` and `att` values must representas a voxel in the image.
+    The calculations are given assuming a voxel value. Hence, all the `tau`,
+    `w`, `cbf` and `att` values must represent a voxel in the image.
 
     Note:
         The CBF value is the original scale, without assuming the normalized
@@ -323,6 +323,34 @@ def asl_model_multi_te(
 def asl_model_multi_dw(
     b_values: list, A1: list, D1: float, A2: list, D2: float
 ):
+    """Multi Diffusion-Weighted (DW) ASL model for diffusion parameter calculation.
+
+    This function calculates the multi-compartment diffusion signal for ASL data
+    with multiple diffusion weighting (b-values). It models the signal decay
+    using a bi-exponential model with two diffusion compartments.
+
+    The model equation used is:
+    S(b) = A1 * exp(-b * D1) + A2 * exp(-b * D2)
+
+    where:
+    - S(b) is the signal at b-value b
+    - A1, A2 are the amplitudes for each compartment
+    - D1, D2 are the diffusion coefficients for each compartment
+
+    Args:
+        b_values (list): List of diffusion b-values (s/mm²).
+        A1 (list): Amplitude values for the first diffusion compartment.
+        D1 (float): Diffusion coefficient for the first compartment (mm²/s).
+        A2 (list): Amplitude values for the second diffusion compartment.
+        D2 (float): Diffusion coefficient for the second compartment (mm²/s).
+
+    Returns:
+        numpy.ndarray: Array of calculated magnetization values for each b-value.
+
+    Note:
+        In case of numerical overflow or runtime errors during computation,
+        the affected values are set to 0.0 to maintain array integrity.
+    """
     mag_total = np.zeros(len(b_values))
 
     for i in range(0, len(b_values)):

asltk/smooth/gaussian.py

@@ -9,7 +9,7 @@
 def isotropic_gaussian(data, sigma: float = 1.0):
     """Smooth the data using a isotropic Gaussian kernel.
 
-    This method assumes that the same kernal size will be applied over all the
+    This method assumes that the same kernel size will be applied over all the
     volume dimension. The method uses the `SimpleITK` library to apply the
     smoothing.
 
@@ -21,7 +21,7 @@ def isotropic_gaussian(data, sigma: float = 1.0):
     Important:
         The kernel size, given by the sigma value, is referred to number of
         voxels considered to apply the smoothing. Therefore, when the voxel
-        resolution is low (tipically for ASL data is around 3-4 mm), the sigma
+        resolution is low (typically for ASL data is around 3-4 mm), the sigma
         value should be around 0.5-2, depending on the desired smoothing effect.
 
     Parameters