Core Lib Documentation: Poseidon module (#6754)

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

corelib/src/poseidon.cairo

@@ -1,3 +1,28 @@
+//! Poseidon hash related traits implementations and functions.
+//!
+//! This module provides cryptographic hash functions based on the Poseidon permutation.
+//!
+//! The Poseidon hash function is an arithmetic-friendly hash function optimized for use in
+//! zero-knowledge proof systems. This module implements the Poseidon hash using a sponge
+//! construction for arbitrary-length inputs.
+//!
+//! # Examples
+//!
+//! ```
+//! use core::hash::HashStateTrait;
+//! use core::poseidon::PoseidonTrait;
+//!
+//! // Create a new hash state
+//! let mut state = PoseidonTrait::new();
+//!
+//! // Update with values
+//! state = state.update(1);
+//! state = state.update(2);
+//!
+//! // Finalize to get the hash
+//! let hash = state.finalize();
+//! ```
+
 use crate::array::Span;
 use crate::array::SpanTrait;
 use crate::option::OptionTrait;
@@ -18,9 +43,18 @@ pub struct HashState {
     pub odd: bool,
 }
 
+/// A trait for creating a new Poseidon hash state.
 #[generate_trait]
 pub impl PoseidonImpl of PoseidonTrait {
-    /// Creates an initial state.
+    /// Creates an initial state with all fields set to 0.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use core::poseidon::PoseidonTrait;
+    ///
+    /// let mut state = PoseidonTrait::new();
+    /// ```
     #[inline]
     fn new() -> HashState {
         HashState { s0: 0, s1: 0, s2: 0, odd: false }
@@ -34,6 +68,17 @@ impl HashStateDefault of Default<HashState> {
 }
 
 impl HashStateImpl of HashStateTrait<HashState> {
+    /// Takes the current state and updates it with a `felt252` value using the Hades permutation.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use core::hash::HashStateTrait;
+    /// use core::poseidon::PoseidonTrait;
+    ///
+    /// let mut state = PoseidonTrait::new();
+    /// state = state.update(1);
+    /// ```
     #[inline]
     fn update(self: HashState, value: felt252) -> HashState {
         if self.odd {
@@ -44,6 +89,19 @@ impl HashStateImpl of HashStateTrait<HashState> {
         }
     }
 
+    /// Takes the current state, applies the Hades permutation and returns the hash result.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use core::hash::HashStateTrait;
+    /// use core::poseidon::PoseidonTrait;
+    ///
+    /// let mut state = PoseidonTrait::new();
+    /// let hash = state.update(1).update(2).finalize();
+    ///
+    /// assert!(hash == 0x0371cb6995ea5e7effcd2e174de264b5b407027a75a231a70c2c8d196107f0e7);
+    /// ```
     #[inline]
     fn finalize(self: HashState) -> felt252 {
         if self.odd {
@@ -56,17 +114,25 @@ impl HashStateImpl of HashStateTrait<HashState> {
     }
 }
 
-/// Computes the Poseidon hash on the given input.
-///
+/// Computes the Poseidon hash on the given span input.
 /// Applies the sponge construction to digest many elements.
 /// To distinguish between use cases, the capacity element is initialized to 0.
 /// To distinguish between different input sizes always pads with 1, and possibly with another 0 to
 /// complete to an even-sized input.
+///
+/// # Examples
+///
+/// ```
+/// let span = [1, 2].span();
+/// let hash = poseidon_hash_span(span);
+///
+/// assert!(hash == 0x0371cb6995ea5e7effcd2e174de264b5b407027a75a231a70c2c8d196107f0e7);
+/// ```
 pub fn poseidon_hash_span(mut span: Span<felt252>) -> felt252 {
     _poseidon_hash_span_inner(crate::gas::get_builtin_costs(), (0, 0, 0), ref span)
 }
 
-/// Helper function for poseidon_hash_span.
+/// Helper function for `poseidon_hash_span`.
 fn _poseidon_hash_span_inner(
     builtin_costs: crate::gas::BuiltinCosts,
     state: (felt252, felt252, felt252),