Document runnable

Author: toroidal-code

include/runnable.hpp

@@ -1,42 +1,55 @@
 #ifndef RUNNABLE_H
 #define RUNNABLE_H
+#include <memory>
 #include <string>
-#include <experimental/optional>
 
+/**
+ * The base class for all objects that comprise some abstract structure
+ * with a nesting concept. Used to propogate ('pass') failures from leaf
+ * to root without exceptions (and/or code-jumping), thus allowing
+ * execution to continue virtually uninterrupted.
+ */
 class Child {
-  // represents whether the children were all healthy/successful.
+  std::shared_ptr<Child> parent = nullptr;  // The parent of this Child.
+
+  // Represents whether the Child is healthy (has not failed).
+  // A Child is healthy if and only if all of its children are healthy.
+  // All instances of Child start out healthy.
   bool status = true;
-  std::experimental::optional<Child*> parent;
 
  public:
   virtual ~Child(){};
 
-  std::string padding();
-
-  bool has_parent() { return static_cast<bool>(parent); }
-  Child* get_parent() { return parent.value(); }
-  void set_parent(Child* parent) { this->parent = parent; }
+  bool has_parent() { return (parent != nullptr); }
+  std::shared_ptr<Child> get_parent() { return parent; }
+  void set_parent(Child* parent) {
+    this->parent = std::shared_ptr<Child>(parent);
+  }
+  void set_parent(std::shared_ptr<Child> parent) { this->parent = parent; }
+  void set_parent(Child& parent) {
+    this->parent = std::shared_ptr<Child>(&parent);
+  }
 
   bool get_status() { return this->status; }
   void failed() {
     this->status = false;
     // propogates the failure up the tree
-    if (parent) parent.value()->failed();
+    if (has_parent()) this->get_parent()->failed();
+  }
+
+  std::string padding() {
+    return has_parent() ? get_parent()->padding() + "  " : "";
   }
 };
 
+/**
+ *
+ *
+ */
 class Runnable : public Child {
  public:
   virtual ~Runnable() {}
   virtual bool run() = 0;
 };
 
-std::string Child::padding() {
-  if (has_parent()) {
-    return get_parent()->padding() + "  ";
-  } else {
-    return "";
-  }
-}
-
 #endif /* RUNNABLE_H */