M README.md → README.md

@@ -12,10 +12,11 @@
 ## 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 @@ ```shell
 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.
 

M src/merkle/merkle_tree.rs → src/merkle/merkle_tree.rs

@@ -68,7 +68,7 @@ ///
     /// # 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 @@ ///
     /// # 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()));

M src/merkle/path_set.rs → src/merkle/path_set.rs

@@ -46,7 +46,7 @@ /// Returns a node at the specified index.
     ///
     /// # 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 @@ /// not included in the path.
     ///
     /// # 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 @@ /// specify the leaf node at which the path starts.
     ///
     /// # 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 @@ index.move_up();
             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 {