Added documentation for the debug tooling

src/debug_tools/diff.rs

@@ -1,3 +1,30 @@
+//! Diffing tools to compare two tries against each other. Useful when you want
+//! to find where the tries diverge from one other.
+//!
+//! There are a few considerations when implementing the logic to create a trie
+//! diff:
+//! - What should be reported when the trie node structures diverge (eg. two
+//!   different node types proceeding a given common node)?
+//! - If there are multiple structural differences, how do we discover the
+//!   smallest difference to report back?
+//!
+//! If the node types between the tries (structure) are identical but some
+//! values are different, then these types of diffs are easy to detect and
+//! report the lowest difference. Structural differences are more challenging
+//! and a bit hard to report well. There are two approaches (only one currently
+//! is implemented) in how to detect structural differences:
+//! - Top-down search
+//! - Bottom-up search
+//!
+//! These two searches are somewhat self-explanatory:
+//! - Top-down will find the highest point of a structural divergence and report
+//!   it. If there are multiple divergences, then only the one that is the
+//!   highest in the trie will be reported.
+//! - Bottom-up (not implemented) is a lot more complex to implement, but will
+//!   attempt to find the smallest structural trie difference between the trie.
+//!   If there are multiple differences, then this will likely be what you want
+//!   to use.
+
 use std::fmt::{self, Debug};
 use std::{fmt::Display, ops::Deref};
 
@@ -53,6 +80,7 @@ impl DiffDetectionState {
     }
 }
 
+/// A point (node) between the two tries where the children differ.
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 pub struct DiffPoint {
     pub depth: usize,
@@ -82,6 +110,7 @@ impl DiffPoint {
     }
 }
 
+// TODO: Redo display method so this is more readable...
 impl Display for DiffPoint {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "Point Diff {{depth: {}, ", self.depth)?;
@@ -92,6 +121,7 @@ impl Display for DiffPoint {
     }
 }
 
+/// Meta information for a node in a trie.
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 pub struct NodeInfo {
     key: Nibbles,
@@ -103,6 +133,7 @@ pub struct NodeInfo {
     hash: H256,
 }
 
+// TODO: Redo display method so this is more readable...
 impl Display for NodeInfo {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "(key: {:x} ", self.key)?;
@@ -128,6 +159,8 @@ impl NodeInfo {
     }
 }
 
+/// Create a diff between two tries. Will perform both types of diff searches
+/// (top-down & bottom-up).
 pub fn create_diff_between_tries(a: &HashedPartialTrie, b: &HashedPartialTrie) -> TrieDiff {
     TrieDiff {
         latest_diff_res: find_latest_diff_point_where_tries_begin_to_diff(a, b),
@@ -198,7 +231,7 @@ impl DepthNodeDiffState {
     }
 }
 
-// State that is copied per recursive call.
+/// State that is copied per recursive call.
 #[derive(Clone, Debug)]
 struct DepthDiffPerCallState<'a> {
     a: &'a HashedPartialTrie,
@@ -429,6 +462,7 @@ mod tests {
         assert_eq!(diff.latest_diff_res, Some(expected));
     }
 
+    // TODO: Will finish these tests later (low-priority).
     #[test]
     #[ignore]
     fn depth_single_node_node_diffs_work() {

src/debug_tools/mod.rs

@@ -1,3 +1,6 @@
+//! Additional methods that may be useful when diagnosing tries from this
+//! library.
+
 pub mod common;
 pub mod diff;
 pub mod query;

src/debug_tools/query.rs

@@ -1,3 +1,6 @@
+//! Query tooling to report info on the path taken when searching down a trie
+//! with a given key.
+
 use std::fmt::{self, Display};
 
 use ethereum_types::H256;
@@ -10,6 +13,7 @@ use crate::{
     partial_trie::{Node, PartialTrie, WrappedNode},
 };
 
+/// Params controlling how much information is reported in the query output.
 #[derive(Clone, Debug)]
 pub struct DebugQueryParams {
     include_key_piece_per_node: bool,
@@ -59,6 +63,7 @@ impl DebugQueryParamsBuilder {
     }
 }
 
+/// The payload to give to the query function. Construct this from the builder.
 #[derive(Debug)]
 pub struct DebugQuery {
     k: Nibbles,
@@ -185,6 +190,7 @@ impl DebugQueryOutput {
         }
     }
 
+    // TODO: Make the output easier to read...
     fn fmt_query_header(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         writeln!(f, "Query Result {{")?;
 
@@ -194,6 +200,7 @@ impl DebugQueryOutput {
         writeln!(f, "}}")
     }
 
+    // TODO: Make the output easier to read...
     fn fmt_node_based_on_debug_params(
         f: &mut fmt::Formatter<'_>,
         seg: &PathSegment,
@@ -230,6 +237,7 @@ impl DebugQueryOutput {
     }
 }
 
+/// Get debug information on the path taken when querying a key in a given trie.
 pub fn get_path_from_query<T: PartialTrie, Q: Into<DebugQuery>>(
     trie: &Node<T>,
     q: Q,
@@ -248,9 +256,6 @@ fn get_path_from_query_rec<T: PartialTrie>(
     query_out: &mut DebugQueryOutput,
 ) {
     let key_piece = get_key_piece_from_node(node, curr_key);
-
-    println!("key piece: {:x}", key_piece);
-
     let seg = get_segment_from_node_and_key_piece(node, &key_piece);
 
     query_out.node_path.append(seg);
@@ -263,10 +268,6 @@ fn get_path_from_query_rec<T: PartialTrie>(
         Node::Branch { children, value: _ } => {
             let nib = curr_key.pop_next_nibble_front();
 
-            println!("NIB: {:x}", nib);
-
-            // println!("CHILDREN: {:#?}", children);
-
             get_path_from_query_rec(&children[nib as usize], curr_key, query_out)
         }
         Node::Extension { nibbles, child } => {