Apply suggestions from code review.

Co-authored-by: str4d <[email protected]>

Author: nuttycom

shardtree/src/lib.rs

@@ -116,6 +116,37 @@ impl<
 
     /// Adds the provided checkpoint to the set of checkpoints to be retained
     /// across pruning operations.
+    ///
+    /// TODO: A bit more documentation.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use incrementalmerkletree::Retention;
+    /// use shardtree::ShardTree;
+    ///
+    /// # fn load_shardtree_from_disk() -> ShardTree<SomeShardStore> {
+    /// #     todo!("Kris returns something useful for testing here.")
+    /// # }
+    /// # fn checkpoints_to_retain() -> Vec<SomeCheckpointId> {
+    /// #     vec![] // TODO: Return something useful for testing here.
+    /// # }
+    /// # fn get_next_leaf() -> SomeLeafType {
+    /// #     todo!("Kris returns something useful for testing here.")
+    /// # }
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// let mut tree = load_shardtree_from_disk();
+    ///
+    /// // The required checkpoints are stored separately from the tree.
+    /// for checkpoint_id in checkpoints_to_retain() {
+    ///     tree.ensure_retained(checkpoint_id);
+    /// }
+    ///
+    /// // Now perform operations that might prune the tree.
+    /// tree.append(get_next_leaf(), Retention::Ephemeral)?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn ensure_retained(&mut self, checkpoint_id: C) {
         self.to_retain.insert(checkpoint_id);
     }