Improved docstrings

Author: lucasimi

src/tdamapper/cover.py

@@ -27,6 +27,28 @@
 
 
 class _Pullback(Generic[S_contra, T_contra]):
+    """
+    Pullback pseudo-metric function.
+
+    This class is used to adapt a metric function that operates on a
+    transformed space to work with the original space. It applies a function
+    to the input data before computing the distance, effectively pulling back
+    the metric to the original space.
+
+    Given a function :math:`f: X \to Y` and a metric
+    :math:`d: Y \times Y \to \\mathbb{R}`,
+    this class defines a new pseudo-metric
+    :math:`d': X \times X \to \\mathbb{R}` such that:
+    :math:`d'(x_1, x_2) = d(f(x_1), f(x_2))`.
+
+    When :math:`f` is injective, this pseudo-metric :math:`d'` is a true
+    metric. If :math:`f` is not injective, it is a pseudo-metric, meaning it
+    may not satisfy the identity of two objects :math:`x_1`, :math:`x_2` with
+    :math:`d'(x_1, x_2) = 0`.
+
+    :param fun: A function that transforms the input data.
+    :param dist: A metric function that operates on the transformed data.
+    """
 
     def __init__(
         self, fun: Callable[[S_contra], T_contra], dist: Metric[T_contra]
@@ -35,10 +57,24 @@ def __init__(
         self.dist = dist
 
     def __call__(self, x: S_contra, y: S_contra) -> float:
+        """
+        Compute the distance between two points in the original space
+        using the pullback metric.
+
+        This method applies the transformation function to both points and
+        then computes the distance using the provided metric function.
+
+        :param x: A point in the original space.
+        :param y: Another point in the original space.
+        :return: The distance between the transformed points in the metric space.
+        """
         return self.dist(self.fun(x), self.fun(y))
 
 
 def _snd(x: tuple[T, ...]) -> T:
+    """
+    Extract the second element from a tuple.
+    """
     return x[1]
 
 
@@ -242,6 +278,35 @@ def apply(self, X: ArrayRead[T_contra]) -> Iterator[list[int]]:
 
 
 class BaseCubicalCover:
+    """
+    Base class for cubical cover algorithms, which cover data with open
+    hypercubes of uniform size and overlap. This class provides the basic
+    functionality for cubical covers, including the initialization of parameters
+    and the methods for computing the center of a hypercube and its overlap.
+
+    A hypercube is a multidimensional generalization of a square or a cube.
+    The size and overlap of the hypercubes are determined by the number of
+    intervals and the overlap fraction parameters. This class maps each point
+    to the hypercube with the nearest center.
+
+    :param n_intervals: The number of intervals to use for each dimension.
+        Must be positive and less than or equal to the length of the dataset.
+        Defaults to 1.
+    :param overlap_frac: The fraction of overlap between adjacent intervals on
+        each dimension, must be in the range (0.0, 0.5]. If not specified, the
+        overlap_frac is computed such that the volume of the overlap within
+        each hypercube is half the total volume. Defaults to None.
+    :param kind: Specifies whether to use a flat or a hierarchical vantage
+        point tree. Acceptable values are 'flat' or 'hierarchical'. Defaults to
+        'flat'.
+    :param leaf_capacity: The maximum number of points in a leaf node of the
+        vantage point tree. Must be a positive value. Defaults to 1.
+    :param leaf_radius: The radius of the leaf nodes. If not specified, it
+        defaults to the value of `radius`. Must be a positive value. Defaults
+        to None.
+    :param pivoting: The method used for pivoting in the vantage point tree.
+        Acceptable values are None, 'random', or 'furthest'. Defaults to None.
+    """
 
     _overlap_frac: float
     _n_intervals: int

src/tdamapper/protocols.py

@@ -1,7 +1,12 @@
 """
-This module defines various protocols used in the tdamapper library. These
-protocols specify the expected behavior of different components such as arrays,
-metrics, covers, clustering algorithms, and spatial search algorithms.
+Protocols for type hinting in tdamapper.
+
+These protocols define the expected interfaces for various components
+used in the tdamapper library, such as array-like structures, metrics,
+cover algorithms, clustering algorithms, and spatial search algorithms.
+They are used to ensure that the components adhere to the expected
+behaviors and can be used interchangeably in the library's functions
+and methods.
 """
 
 from __future__ import annotations