Core Lib Documentation: fmt module

corelib/src/fmt.cairo

@@ -1,3 +1,17 @@
+//! Functionality for formatting values.
+//!
+//! The main components of this module are:
+//!
+//! - `Error`: A type representing formatting errors.
+//! - `Formatter`: A struct that holds the configuration and buffer for formatting.
+//! - `Display`: A trait for standard formatting using the empty format ("{}").
+//! - `Debug`: A trait for debug formatting using the empty format ("{:?}").
+//! - `LowerHex`: A trait for hex formatting in lower case.
+//!
+//! The module includes implementations of the [`Display`], [`Debug`] and [`LowerHex`] traits for
+//! various types.
+
+/// Dedicated type for representing formatting errors.
 #[derive(Drop)]
 pub struct Error {}
 
@@ -9,6 +23,13 @@ pub struct Formatter {
 }
 
 /// A trait for standard formatting, using the empty format ("{}").
+///
+/// # Examples
+///
+/// ```
+/// let word: ByteArray = "123";
+/// println!("{}", word);
+/// ```
 pub trait Display<T> {
     fn fmt(self: @T, ref f: Formatter) -> Result<(), Error>;
 }
@@ -72,6 +93,13 @@ impl DisplaySnapshot<T, +Display<T>> of Display<@T> {
 }
 
 /// A trait for debug formatting, using the empty format ("{:?}").
+///
+/// # Examples
+///
+/// ```
+/// let word: ByteArray = "123";
+/// println!("{:?}", word);
+/// ```
 pub trait Debug<T> {
     fn fmt(self: @T, ref f: Formatter) -> Result<(), Error>;
 }
@@ -125,7 +153,6 @@ impl DebugSnapshot<T, +Debug<T>> of Debug<@T> {
     }
 }
 
-/// Tuple `Debug` implementation.
 impl TupleDebug<
     T,
     impl TSF: crate::metaprogramming::TupleSnapForward<T>,
@@ -139,7 +166,6 @@ impl TupleDebug<
     }
 }
 
-/// Fixed sized array `Debug` implementation.
 impl FixedSizedArrayDebug<
     T,
     impl TSF: crate::metaprogramming::TupleSnapForward<T>,
@@ -158,21 +184,18 @@ trait TupleDebugHelper<T> {
     fn fmt(value: T, ref f: Formatter) -> Result<(), Error>;
 }
 
-/// An implementation of `TupleDebugHelper` for snapshots of types with `Debug` implementations.
 impl TupleDebugHelperFromDebug<T, +Debug<T>> of TupleDebugHelper<@T> {
     fn fmt(value: @T, ref f: Formatter) -> Result<(), Error> {
         Debug::fmt(value, ref f)
     }
 }
 
-/// `Debug` impl for tuples of size 0.
 impl TupleDebugHelperTuple0 of TupleDebugHelper<()> {
     fn fmt(value: (), ref f: Formatter) -> Result<(), Error> {
         Result::Ok(())
     }
 }
 
-/// `Debug` impl for tuples of size 1.
 impl TupleDebugHelperTuple1<E0, +TupleDebugHelper<@E0>> of TupleDebugHelper<(@E0,)> {
     fn fmt(value: (@E0,), ref f: Formatter) -> Result<(), Error> {
         let (e0,) = value;
@@ -181,7 +204,6 @@ impl TupleDebugHelperTuple1<E0, +TupleDebugHelper<@E0>> of TupleDebugHelper<(@E0
     }
 }
 
-/// `Debug` impl for tuples of size 2.
 impl TupleDebugHelperTuple2<
     E0, E1, +TupleDebugHelper<@E0>, +TupleDebugHelper<@E1>,
 > of TupleDebugHelper<(@E0, @E1)> {
@@ -193,8 +215,8 @@ impl TupleDebugHelperTuple2<
     }
 }
 
-/// `Debug` impl for tuples of size 3 and above.
-/// Not starting from size 1 since we have special cases for 0 and 1.
+// `Debug` impl for tuples of size 3 and above.
+// Not starting from size 1 nor 2 since we have special cases for 1 and 2.
 impl TupleDebugHelperTupleNext<
     T,
     impl TS: crate::metaprogramming::TupleSplit<T>,
@@ -211,23 +233,21 @@ impl TupleDebugHelperTupleNext<
     }
 }
 
-/// `Debug` impl for fixed sized arrays of size 0.
 impl TupleDebugHelperFixedSizedArray0<T> of TupleDebugHelper<[@T; 0]> {
     fn fmt(value: [@T; 0], ref f: Formatter) -> Result<(), Error> {
         Result::Ok(())
     }
 }
 
-/// `Debug` impl for fixed sized arrays of size 1.
 impl TupleDebugHelperFixedSizedArray1<T, +TupleDebugHelper<@T>> of TupleDebugHelper<[@T; 1]> {
     fn fmt(value: [@T; 1], ref f: Formatter) -> Result<(), Error> {
         let [e0] = value;
         TupleDebugHelper::fmt(e0, ref f)
     }
 }
 
-/// `Debug` impl for fixed sized arrays of size 2 and above.
-/// Not starting from size 1 since we have a special case for 0.
+// `Debug` impl for fixed sized arrays of size 2 and above.
+// Not starting from size 1 since we have a special case for 1.
 impl TupleDebugHelperFixedSizedArrayNext<
     T,
     const N: usize,
@@ -289,10 +309,12 @@ impl SpanTDebug<T, +Debug<T>> of Debug<Span<T>> {
     }
 }
 
-/// Impls for `Debug` and `LowerHex` for types that can be converted into `felt252` using the `Into`
-/// trait.
-/// Usage example:
-/// ```ignore
+/// Implementations for `Debug` and `LowerHex` for types that can be converted into `felt252` using
+/// the `Into` trait.
+///
+/// # Examples
+///
+/// ```
 /// impl MyTypeDebug = crate::fmt::into_felt252_based::DebugImpl<MyType>;`
 /// impl MyTypeLowerHex = crate::fmt::into_felt252_based::LowerHexImpl<MyType>;
 /// ```
@@ -302,6 +324,7 @@ pub mod into_felt252_based {
             crate::fmt::DebugInteger::<felt252>::fmt(@(*self).into(), ref f)
         }
     }
+
     pub impl LowerHexImpl<T, +Into<T, felt252>, +Copy<T>> of core::fmt::LowerHex<T> {
         fn fmt(self: @T, ref f: core::fmt::Formatter) -> Result<(), core::fmt::Error> {
             core::fmt::LowerHexInteger::<felt252>::fmt(@(*self).into(), ref f)