Upgraded Documentation of the Library

Author: Ian

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "single-utilities"
-version = "0.8.4"
+version = "0.8.5"
 edition = "2024"
 description = "This crate provdes types, traits and utility functions to the single-rust ecosystem that can be universally used. You can also use it within your own ecosystem 👀"
 homepage = "https://singlerust.com"

Cargo.toml

@@ -1,3 +1,62 @@
+//! # Single Utilities
+//!
+//! A comprehensive utilities library designed for the SingleRust ecosystem and beyond.
+//! This crate provides fundamental building blocks for mathematical computations,
+//! data processing, and algorithmic operations commonly needed in scientific computing,
+//! machine learning, and data analysis applications.
+//!
+//! ## Overview
+//!
+//! Single Utilities offers a collection of traits and types that abstract common
+//! patterns in numerical computing while maintaining flexibility and performance.
+//! While primarily developed for the SingleRust ecosystem, the library is designed
+//! with modularity and interoperability in mind, making it suitable for use with
+//! other Rust libraries and frameworks.
+//!
+//! ## Features
+//!
+//! ### Traits Module
+//! - **Numeric Operations**: Comprehensive traits for basic and advanced numeric operations
+//! - **Thread Safety**: Thread-safe variants for concurrent and parallel computations
+//! - **SIMD Support**: Optional SIMD-accelerated operations when the "simd" feature is enabled
+//! - **Type Constraints**: Flexible trait bounds for generic mathematical algorithms
+//!
+//! ### Types Module
+//! - **Direction Handling**: Utilities for row/column-oriented operations
+//! - **Distance Metrics**: Common distance functions for similarity calculations
+//! - **Batch Processing**: Identifiers and utilities for batch operations
+//!
+//! ## Usage
+//!
+//! ```rust
+//! use single_utilities::traits::NumericOps;
+//! use single_utilities::types::{Direction, DistanceMetric};
+//!
+//! // Use traits to constrain generic functions
+//! fn process_data<T: NumericOps>(data: &[T]) -> T {
+//!     // Your numeric processing logic here
+//!     T::zero()
+//! }
+//!
+//! // Use direction for matrix operations
+//! let direction = Direction::ROW;
+//! if direction.is_row() {
+//!     // Process row-wise
+//! }
+//! ```
+//!
+//! ## Feature Flags
+//!
+//! - `simd`: Enables SIMD-accelerated operations using the `simba` crate
+//!
+//! ## Compatibility
+//!
+//! This library is designed to work seamlessly with:
+//! - The broader SingleRust ecosystem
+//! - Standard numeric libraries like `num-traits`
+//! - SIMD libraries like `simba` (when feature is enabled)
+//! - Custom mathematical and scientific computing libraries
+
 pub mod traits;
 
 pub mod types;

src/lib.rs

@@ -6,6 +6,12 @@ use std::fmt::Debug;
 use std::iter::Sum;
 use std::ops::{Add, AddAssign, MulAssign, SubAssign};
 
+/// A trait defining fundamental numeric operations and constraints.
+/// 
+/// This trait bundles common numeric operations required for mathematical computations,
+/// including zero/one elements, numeric casting, assignment operations, ordering, 
+/// bounds checking, and basic arithmetic. Types implementing this trait can be used
+/// in generic numeric algorithms.
 pub trait NumericOps:
     Zero
     + One
@@ -40,28 +46,55 @@ impl<
 {
 }
 
+/// A thread-safe version of `NumericOps`.
+/// 
+/// This trait extends `NumericOps` with `Send + Sync` bounds, making it suitable
+/// for use in concurrent and parallel computations where data needs to be 
+/// safely shared across threads.
 pub trait NumericOpsTS: NumericOps + Send + Sync {}
 
 impl<T: NumericOps + Send + Sync> NumericOpsTS for T {}
 
+/// A trait for floating-point numeric operations.
+/// 
+/// Extends `NumericOps` with floating-point specific operations from the `num_traits`
+/// crate, including floating-point arithmetic, primitive conversions, and core 
+/// floating-point functionality. This trait is designed for types that represent
+/// real numbers with decimal precision.
 pub trait FloatOps:
     NumericOps + num_traits::Float + FromPrimitive + ToPrimitive + FloatCore
 {
 }
 
 impl<T: NumericOps + num_traits::Float + FromPrimitive + ToPrimitive + FloatCore> FloatOps for T {}
 
+/// A thread-safe version of `FloatOps`.
+/// 
+/// This trait extends `FloatOps` with `Send + Sync` bounds for safe use in
+/// concurrent floating-point computations across multiple threads.
 pub trait FloatOpsTS: FloatOps + Sync + Send {}
 
 impl<T: FloatOps + Send + Sync> FloatOpsTS for T {}
 
 #[cfg(feature = "simd")]
+/// A SIMD-enabled floating-point operations trait.
+/// 
+/// Extends `FloatOpsTS` with SIMD (Single Instruction, Multiple Data) capabilities
+/// from the `simba` crate. This enables vectorized floating-point operations for
+/// improved performance in mathematical computations.
+/// 
+/// Only available when the "simd" feature is enabled.
 pub trait FloatOpsTSSimba: FloatOpsTS + SimdRealField + RealField {}
 
 #[cfg(feature = "simd")]
 impl<T: FloatOpsTS + SimdRealField + RealField> FloatOpsTSSimba for T {}
 
-// Define a type alias for our numeric constraints
+/// A trait for numeric types suitable for normalization operations.
+/// 
+/// This trait combines floating-point arithmetic with assignment operations,
+/// summation capabilities, and numeric casting. It's specifically designed
+/// for types that need to participate in normalization algorithms where
+/// values are scaled or adjusted relative to some total or maximum.
 pub trait NumericNormalize:
     num_traits::Float + std::ops::AddAssign + std::iter::Sum + num_traits::NumCast
 {
@@ -73,7 +106,16 @@ impl<T> NumericNormalize for T where
 {
 }
 
+/// A trait for vectors that can be resized and filled with default values.
+/// 
+/// Provides functionality to clear a vector and resize it to a specific length,
+/// filling all positions with the default value of the element type. This is
+/// useful for initializing or resetting vectors to a known state.
 pub trait ZeroVec {
+    /// Clears the vector and resizes it to the specified length, filling with default values.
+    /// 
+    /// # Arguments
+    /// * `len` - The desired length of the vector
     fn zero_len(&mut self, len: usize);
 }
 
@@ -85,6 +127,12 @@ impl<T: Default + Clone> ZeroVec for Vec<T> {
     }
 }
 
+/// A trait for unsigned integer types suitable for indexing operations.
+/// 
+/// This trait combines unsigned integer properties with zero/one elements,
+/// ordering capabilities, and conversion to/from `usize`. It's designed for
+/// types that can be safely used as array or vector indices while providing
+/// mathematical operations and bounds checking.
 pub trait UIndex:
     Unsigned + Zero + One + Copy + Eq + Ord + PartialOrd + From<usize> + Into<usize> + Bounded
 {
@@ -95,6 +143,12 @@ impl<I: Unsigned + Zero + One + Copy + Eq + Ord + PartialOrd + From<usize> + Int
 {
 }
 
+/// A trait for scalar values used in mathematical computations.
+/// 
+/// This trait defines the minimal requirements for types that can be used as
+/// scalar values in mathematical operations. It requires static lifetime,
+/// cloning capability, equality comparison, and debug formatting. This is
+/// typically used as a constraint for generic mathematical algorithms.
 pub trait Scalar: 'static + Clone + PartialEq + Debug {}
 
 impl<T: 'static + Clone + PartialEq + Debug> Scalar for T {}

src/traits/mod.rs

@@ -1,7 +1,13 @@
 use std::hash::Hash;
 
+/// Represents the direction of operations in matrix or array computations.
+/// 
+/// This enum is used to specify whether operations should be performed
+/// along rows or columns of a data structure.
 pub enum Direction {
+    /// Operations performed along columns (vertical direction)
     COLUMN,
+    /// Operations performed along rows (horizontal direction)
     ROW,
 }
 
@@ -15,6 +21,10 @@ impl Clone for Direction {
 }
 
 impl Direction {
+    /// Checks if the direction is row-wise.
+    /// 
+    /// # Returns
+    /// `true` if the direction is `ROW`, `false` if it's `COLUMN`
     pub fn is_row(&self) -> bool {
         match self {
             Self::ROW => true,
@@ -23,6 +33,11 @@ impl Direction {
     }
 }
 
+/// A trait for types that can serve as batch identifiers.
+/// 
+/// This trait is used to identify and group data in batch processing operations.
+/// Types implementing this trait must be cloneable, comparable for equality,
+/// and hashable for efficient lookup operations.
 pub trait BatchIdentifier: Clone + Eq + Hash {}
 
 // Implement BatchIdentifier for common types
@@ -32,12 +47,17 @@ impl BatchIdentifier for i32 {}
 impl BatchIdentifier for u32 {}
 impl BatchIdentifier for usize {}
 
+/// Enumeration of distance metrics for mathematical computations.
+/// 
+/// This enum defines common distance metrics used in machine learning,
+/// clustering, and similarity calculations. Each variant represents
+/// a different approach to measuring the distance between points or vectors.
 #[derive(Debug, Clone, Copy)]
 pub enum DistanceMetric {
-    /// Euclidean distance
+    /// Euclidean distance (L2 norm) - straight-line distance between points
     Euclidean,
-    /// Manhattan distance
+    /// Manhattan distance (L1 norm) - sum of absolute differences along each dimension
     Manhattan,
-    /// Cosine distance
+    /// Cosine distance - measures the cosine of the angle between vectors
     Cosine,
 }