From 67a5d6ff298e0285734a3924ae43c871a8e29696 Mon Sep 17 00:00:00 2001
From: Kris Nuttycombe <kris@nutty.land>
Date: Wed, 1 Dec 2021 15:41:33 -0700
Subject: [PATCH] Fix documentation of tree methods.

---
 src/bridgetree.rs |  7 +++++++
 src/lib.rs        | 18 +++++++++++++-----
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/src/bridgetree.rs b/src/bridgetree.rs
index 5796c94..7e805f6 100644
--- a/src/bridgetree.rs
+++ b/src/bridgetree.rs
@@ -641,12 +641,19 @@ impl<H: Hashable + Hash + Eq + Debug, const DEPTH: u8> Debug for BridgeTree<H, D
     }
 }
 
+/// An internal-only enum used to indicate whether the `witness_internal`
+/// method is being called in the context of marking a leaf as one for
+/// which it needs to be able to construct a witness, or whether that
+/// leaf is merely being marked as a checkpoint to which it is possible
+/// to rewind.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 enum BoundaryType {
     Witness,
     Checkpoint,
 }
 
+/// Errors that can appear when validating the internal consistency of a `[MerkleBridge]`
+/// value when constructing a bridge from its constituent parts.
 #[derive(Debug, Clone)]
 pub enum BridgeTreeError {
     IncorrectIncompleteIndex,
diff --git a/src/lib.rs b/src/lib.rs
index 92c5d30..899433e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -240,13 +240,21 @@ pub trait Tree<H>: Frontier<H> {
     // at which their being spent is is max_checkpoints blocks is the past,
     // the witness can be discarded.
 
-    /// Marks the current tree state as a checkpoint if it is not already a
-    /// checkpoint.
+    /// Creates a new checkpoint for the current tree state. It is valid to
+    /// have multiple checkpoints for the same tree state, and each `rewind`
+    /// call will remove a single checkpoint.
     fn checkpoint(&mut self);
 
-    /// Rewinds the tree state to the previous checkpoint. This function will
-    /// fail and return false if there is no previous checkpoint or in the event
-    /// witness data would be destroyed in the process.
+    /// Rewinds the tree state to the previous checkpoint, and then removes
+    /// that checkpoint record. If there are multiple checkpoints at a given
+    /// tree state, the tree state will not be altered until all checkpoints
+    /// at that tree state have been removed using `rewind`. This function
+    /// will fail and return false if there is no previous checkpoint or in
+    /// the event witness data would be destroyed in the process.
+    ///
+    /// In the case that this method returns `false`, the user should have
+    /// explicitly called `remove_witness` for each witnessed leaf marked
+    /// since the last checkpoint.
     fn rewind(&mut self) -> bool;
 
     /// Start a recording of append operations performed on a tree.