From bd57448f56f0817cce952dd1ffcb7d5e1e9794d4 Mon Sep 17 00:00:00 2001
From: vandomej <jacob.vandome15@gmail.com>
Date: Mon, 23 Aug 2021 22:39:45 -0700
Subject: [PATCH] Finishing comments for bracket

---
 gemla/src/bracket/mod.rs | 81 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 77 insertions(+), 4 deletions(-)

diff --git a/gemla/src/bracket/mod.rs b/gemla/src/bracket/mod.rs
index ccee0d7..e1f54b1 100644
--- a/gemla/src/bracket/mod.rs
+++ b/gemla/src/bracket/mod.rs
@@ -121,7 +121,7 @@ pub struct Bracket<T>
 where
     T: genetic_node::GeneticNode,
 {
-    tree: tree::Tree<T>,
+    pub tree: tree::Tree<T>,
     iteration_scaling: IterationScaling,
 }
 
@@ -308,9 +308,9 @@ where
         self
     }
 
-    /// Creates a balanced tree with the given `height` that will be used as a branch of the primary tree.
-    /// This additionally simulates and evaluates nodes in the branch as it is built.
-    pub fn create_new_branch(&self, height: u64) -> Result<tree::Tree<T>, String> {
+    // Creates a balanced tree with the given `height` that will be used as a branch of the primary tree.
+    // This additionally simulates and evaluates nodes in the branch as it is built.
+    fn create_new_branch(&self, height: u64) -> Result<tree::Tree<T>, String> {
         if height == 1 {
             let mut base_node = btree!(*T::initialize()?);
 
@@ -343,6 +343,79 @@ where
     /// 2) Simulating the top node of the current branch.
     /// 3) Comparing the top node of the current branch to the top node of the new branch.
     /// 4) Takes the best performing node and makes it the root of the tree. 
+    /// 
+    /// # Examples
+    /// ```
+    /// # use gemla::bracket::*;
+    /// # use serde::{Deserialize, Serialize};
+    /// # use std::fmt;
+    /// # use std::str::FromStr;
+    /// # use std::string::ToString;
+    /// #
+    /// # #[derive(Default, Deserialize, Serialize, Clone)]
+    /// # struct TestState {
+    /// #   pub score: f64,
+    /// # }
+    /// #
+    /// # impl FromStr for TestState {
+    /// #   type Err = String;
+    /// #
+    /// #   fn from_str(s: &str) -> Result<TestState, Self::Err> {
+    /// #       toml::from_str(s).map_err(|_| format!("Unable to parse string {}", s))
+    /// #   }
+    /// # }
+    /// #
+    /// # impl fmt::Display for TestState {
+    /// #     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    /// #         write!(f, "{}", self.score)
+    /// #     }
+    /// # }
+    /// #
+    /// # impl TestState {
+    /// #     fn new(score: f64) -> TestState {
+    /// #         TestState { score: score }
+    /// #     }
+    /// # }
+    /// #
+    /// # impl genetic_node::GeneticNode for TestState {
+    /// #     fn simulate(&mut self, iterations: u64) -> Result<(), String> {
+    /// #         self.score += iterations as f64;
+    /// #         Ok(())
+    /// #     }
+    /// #
+    /// #     fn get_fit_score(&self) -> f64 {
+    /// #         self.score
+    /// #     }
+    /// #
+    /// #     fn calculate_scores_and_trim(&mut self) -> Result<(), String> {
+    /// #         Ok(())
+    /// #     }
+    /// #
+    /// #     fn mutate(&mut self) -> Result<(), String> {
+    /// #         Ok(())
+    /// #     }
+    /// #
+    /// #     fn initialize() -> Result<Box<Self>, String> {
+    /// #         Ok(Box::new(TestState { score: 0.0 }))
+    /// #     }
+    /// # }
+    /// #
+    /// # fn main() {
+    /// let mut bracket = Bracket::<TestState>::initialize("./temp".to_string())
+    ///     .expect("Bracket failed to initialize");
+    /// 
+    /// // Running simulations 3 times
+    /// for _ in 0..3 {
+    ///     bracket
+    ///         .mutate(|b| drop(b.run_simulation_step()))
+    ///         .expect("Failed to run step");
+    /// }
+    /// 
+    /// assert_eq!(bracket.readonly().tree.height(), 4);
+    /// 
+    /// # std::fs::remove_file("./temp").expect("Unable to remove file");
+    /// # }
+    /// ```
     pub fn run_simulation_step(&mut self) -> Result<&mut Self, String> {
         let new_branch = self.create_new_branch(self.tree.height())?;