docs: fix typos in doc comments

README.md

@@ -12,10 +12,11 @@ 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:
 
-* `MerklePathSet`: a collection of Merkle authentication paths all resolving to the same root. The length of the paths can be at most 64.
 * `MerkleTree`: a regular fully-balanced binary Merkle tree. The depth of this tree can be at most 64.
 * `SimpleSmt`: a Sparse Merkle Tree, mapping 63-bit keys to 4-element leaf values.
-* `MerkleError`, `MerklePath`, and `NodeIndex` are Merkle wrappers to assist tree indexation, opening proofs, and report inconsistent arguments/state.
+* `MerklePathSet`: a collection of Merkle authentication paths all resolving to the same root. The length of the paths can be at most 64.
+
+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.
 
 ## Extra
 [Root module](./src/lib.rs) provides a set of constants, types, aliases, and utils required to use the primitives of this library.
@@ -38,7 +39,7 @@ You can use cargo defaults to test the library:
 cargo test
 ```
 
-However, some of the functions are heavy and might take a while for the tests to complete. In order to test in release mode, we have to replicate the same test conditions of the development mode so all debug assertions can be verified.
+However, some of the functions are heavy and might take a while for the tests to complete. In order to test in release mode, we have to replicate the test conditions of the development mode so all debug assertions can be verified.
 
 We do that by enabling some special [flags](https://doc.rust-lang.org/cargo/reference/profiles.html) for the compilation.
 

src/merkle/merkle_tree.rs

@@ -68,7 +68,7 @@ impl MerkleTree {
     /// # Errors
     /// Returns an error if:
     /// * The specified depth is greater than the depth of the tree.
-    /// * The specified index not valid for the specified depth.
+    /// * The specified index is not valid for the specified depth.
     pub fn get_node(&self, index: NodeIndex) -> Result<Word, MerkleError> {
         if index.is_root() {
             return Err(MerkleError::DepthTooSmall(index.depth()));
@@ -88,7 +88,7 @@ impl MerkleTree {
     /// # Errors
     /// Returns an error if:
     /// * The specified depth is greater than the depth of the tree.
-    /// * The specified value not valid for the specified depth.
+    /// * The specified value is not valid for the specified depth.
     pub fn get_path(&self, mut index: NodeIndex) -> Result<MerklePath, MerkleError> {
         if index.is_root() {
             return Err(MerkleError::DepthTooSmall(index.depth()));

src/merkle/path_set.rs

@@ -46,7 +46,7 @@ impl MerklePathSet {
     ///
     /// # Errors
     /// Returns an error if:
-    /// * The specified index not valid for the depth of structure.
+    /// * The specified index is not valid for the depth of structure.
     /// * Requested node does not exist in the set.
     pub fn get_node(&self, index: NodeIndex) -> Result<Word, MerkleError> {
         if !index.with_depth(self.total_depth).is_valid() {
@@ -75,7 +75,7 @@ impl MerklePathSet {
     ///
     /// # Errors
     /// Returns an error if:
-    /// * The specified index not valid for the depth of structure.
+    /// * The specified index is not valid for the depth of structure.
     /// * Node of the requested path does not exist in the set.
     pub fn get_path(&self, index: NodeIndex) -> Result<MerklePath, MerkleError> {
         if !index.with_depth(self.total_depth).is_valid() {
@@ -108,8 +108,8 @@ impl MerklePathSet {
     ///
     /// # Errors
     /// Returns an error if:
-    /// - The specified index is not valid in the context of this Merkle path set (i.e., the index
-    ///   implies a greater depth than is specified for this set).
+    /// - The specified index is is not valid in the context of this Merkle path set (i.e., the
+    ///   index implies a greater depth than is specified for this set).
     /// - The specified path is not consistent with other paths in the set (i.e., resolves to a
     ///   different root).
     pub fn add_path(
@@ -140,7 +140,8 @@ impl MerklePathSet {
             Rpo256::merge(&index.build_node(root.into(), hash.into())).into()
         });
 
-        // TODO review and document this logic
+        // if the path set is empty (the root is all ZEROs), set the root to the root of the added
+        // path; otherwise, the root of the added path must be identical to the current root
         if self.root == [ZERO; 4] {
             self.root = root;
         } else if self.root != root {