Core Lib Documentation: Saturating module (#6809)

Co-authored-by: enitrat <[email protected]>

corelib/src/num/traits/ops/saturating.cairo

@@ -1,18 +1,47 @@
+//! Saturating arithmetic operations for numeric types.
+//!
+//! This module provides traits and implementations for arithmetic operations
+//! that saturate at the numeric type's boundaries instead of overflowing.
+
 /// Performs addition that saturates at the numeric bounds instead of overflowing.
+///
+/// # Examples
+///
+/// ```
+/// use core::num::traits::SaturatingAdd;
+///
+/// assert!(255_u8.saturating_add(1_u8) == 255);
+/// ```
 pub trait SaturatingAdd<T> {
     /// Saturating addition. Computes `self + other`, saturating at the relevant high or low
     /// boundary of the type.
     fn saturating_add(self: T, other: T) -> T;
 }
 
 /// Performs subtraction that saturates at the numeric bounds instead of overflowing.
+///
+/// # Examples
+///
+/// ```
+/// use core::num::traits::SaturatingSub;
+///
+/// assert!(1_u8.saturating_sub(2_u8) == 0);
+/// ```
 pub trait SaturatingSub<T> {
     /// Saturating subtraction. Computes `self - other`, saturating at the relevant high or low
     /// boundary of the type.
     fn saturating_sub(self: T, other: T) -> T;
 }
 
 /// Performs multiplication that saturates at the numeric bounds instead of overflowing.
+///
+/// # Examples
+///
+/// ```
+/// use core::num::traits::SaturatingMul;
+///
+/// assert!(100_u8.saturating_mul(3_u8) == 255);
+/// ```
 pub trait SaturatingMul<T> {
     /// Saturating multiplication. Computes `self * other`, saturating at the relevant high or low
     /// boundary of the type.