docs: add module descriptions

.git-blame-ignore-revs

@@ -1,2 +0,0 @@
-# initial run of pre-commit
-956e4c6fad779ef15eaa27702b26f05f65d31494

README.md

@@ -12,9 +12,9 @@ For performance benchmarks of these hash functions and their comparison to other
 ## Merkle
 [Merkle module](./src/merkle/) provides a set of data structures related to Merkle trees. All these data structures are implemented using the RPO hash function described above. The data structures are:
 
-* `Mmr`: a Merkle mountain range structure designed to function as an append-only log.
-* `MerkleTree`: a regular fully-balanced binary Merkle tree. The depth of this tree can be at most 64.
 * `MerkleStore`: a collection of Merkle trees of different heights designed to efficiently store trees with common subtrees. When instantiated with `RecordingMap`, a Merkle store records all accesses to the original data.
+* `MerkleTree`: a regular fully-balanced binary Merkle tree. The depth of this tree can be at most 64.
+* `Mmr`: a Merkle mountain range structure designed to function as an append-only log.
 * `PartialMerkleTree`: a partial view of a Merkle tree where some sub-trees may not be known. This is similar to a collection of Merkle paths all resolving to the same root. The length of the paths can be at most 64.
 * `SimpleSmt`: a Sparse Merkle Tree (with no compaction), mapping 64-bit keys to 4-element values.
 * `TieredSmt`: a Sparse Merkle tree (with compaction), mapping 4-element keys to 4-element values.
@@ -22,7 +22,7 @@ For performance benchmarks of these hash functions and their comparison to other
 The module also contains additional supporting components such as `NodeIndex`, `MerklePath`,  and `MerkleError`  to assist with tree indexation, opening proofs, and reporting inconsistent arguments/state.
 
 ## Signatures
-[DAS module](./src/dsa) provides a set of digital signature schemes supported by default in Miden VM. Currently, these schemes are:
+[DAS module](./src/dsa) provides a set of digital signature schemes supported by default in the Miden VM. Currently, these schemes are:
 
 * `RPO Falcon512`: a variant of the [Falcon](https://falcon-sign.info/) signature scheme. This variant differs from the standard in that instead of using SHAKE256 hash function in the *hash-to-point* algorithm we use RPO256. This makes the signature more efficient to verify in Miden VM.
 

src/dsa/mod.rs

@@ -1 +1,3 @@
+//! Digital signature schemes supported by default in the Miden VM.
+
 pub mod rpo_falcon512;

src/hash/mod.rs

@@ -1,3 +1,5 @@
+//! Cryptographic hash functions used by the Miden VM and the Miden rollup.
+
 use super::{Felt, FieldElement, StarkField, ONE, ZERO};
 
 pub mod blake;

src/lib.rs

@@ -7,12 +7,12 @@ extern crate alloc;
 pub mod dsa;
 pub mod hash;
 pub mod merkle;
+pub mod rand;
 pub mod utils;
 
 // RE-EXPORTS
 // ================================================================================================
 
-pub use winter_crypto::{RandomCoin, RandomCoinError};
 pub use winter_math::{fields::f64::BaseElement as Felt, FieldElement, StarkField};
 
 // TYPE ALIASES

src/merkle/mod.rs

@@ -1,3 +1,5 @@
+//! Data structures related to Merkle trees based on RPO256 hash function.
+
 use super::{
     hash::rpo::{Rpo256, RpoDigest},
     utils::collections::{vec, BTreeMap, BTreeSet, KvMap, RecordingMap, TryApplyDiff, Vec},

src/rand/mod.rs

@@ -0,0 +1,3 @@
+//! Pseudo-random element generation.
+
+pub use winter_crypto::{RandomCoin, RandomCoinError};

src/utils/mod.rs

@@ -1,3 +1,5 @@
+//! Utilities used in this crate which can also be generally useful downstream.
+
 use super::{utils::string::String, Word};
 use core::fmt::{self, Display, Write};
 
@@ -49,9 +51,10 @@ pub fn bytes_to_hex_string(data: [u8; N]) -> String {
     s
 }
 
+/// Defines errors which can occur during parsing of hexadecimal strings.
 #[derive(Debug)]
 pub enum HexParseError {
-    InvalidLength { expected: usize, got: usize },
+    InvalidLength { expected: usize, actual: usize },
     MissingPrefix,
     InvalidChar,
     OutOfRange,
@@ -60,8 +63,8 @@ pub enum HexParseError {
 impl Display for HexParseError {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
-            HexParseError::InvalidLength { expected, got } => {
-                write!(f, "Hex encoded RpoDigest must have length 66, including the 0x prefix. expected {expected} got {got}")
+            HexParseError::InvalidLength { expected, actual } => {
+                write!(f, "Hex encoded RpoDigest must have length 66, including the 0x prefix. expected {expected} got {actual}")
             }
             HexParseError::MissingPrefix => {
                 write!(f, "Hex encoded RpoDigest must start with 0x prefix")
@@ -83,7 +86,7 @@ impl std::error::Error for HexParseError {}
 pub fn hex_to_bytes<const N: usize>(value: &str) -> Result<[u8; N], HexParseError> {
     let expected: usize = (N * 2) + 2;
     if value.len() != expected {
-        return Err(HexParseError::InvalidLength { expected, got: value.len() });
+        return Err(HexParseError::InvalidLength { expected, actual: value.len() });
     }
 
     if !value.starts_with("0x") {