From a8204affbb8ee383490636822804287f4d1131bd Mon Sep 17 00:00:00 2001
From: Hugo Nie <gnie@ncsu.edu>
Date: Mon, 30 Mar 2020 15:09:36 -0400
Subject: [PATCH] Update FaultTreeUtils.C ref #126

1. make macro #define a method
2. remove all commented sections
3. remove banned keywords
---
 include/utils/FaultTreeUtils.h | 93 +++++++++++++++++++++++++++++-----
 1 file changed, 79 insertions(+), 14 deletions(-)

diff --git a/include/utils/FaultTreeUtils.h b/include/utils/FaultTreeUtils.h
index 302b11edf4..57df9b3a81 100644
--- a/include/utils/FaultTreeUtils.h
+++ b/include/utils/FaultTreeUtils.h
@@ -18,22 +18,35 @@ class Quantification;
 class FaultTree;
 class CException;
 
-
+/**
+ *  String trim method which removes all leading and lagging whitespace in a string
+ */
 std::string trim(const std::string & str);
 
-
+/**
+ *  Converts ASCII string to upper case
+ */
 std::string str2Upper(const std::string & str_in, bool trim_input = false);
 
+/**
+ *  Returns interpolated value at x from parallel arrays ( xData, yData )
+ *  Assumes that xData has at least two elements, is sorted and is strictly monotonic increasing
+ *  boolean argument extrapolate determines behaviour beyond ends of array (if needed)
+ */
 double interpolate(vector_double data, double x, bool extrapolate);
 
-
+/**
+ *  Phi(-∞, x) aka N(x)
+ */
 double normalCDF(double x);
 double normalCDF(double x, double mu, double sigma);
 
 double Clip(double a, double min, double max);
 
 std::vector<double> genQuantificationRVec(double dataPoint, int n, std::vector<double> rv);
-}
+} // namespace FTAUtils
+
+/********************* Fault Tree Definition *********************/
 
 class FTAUtils::FaultTree
 {
@@ -57,63 +70,115 @@ class FTAUtils::FaultTree
     }
   };
 
-
+  /**
+   * Constructor for fault tree class
+   * Default value of root is the first node in file
+   */
   FaultTree(std::string file_name, std::string root = "");
   FaultTree(set_string & sets_link, std::map<std::string, _node *> _node_base);
 
-
+  /**
+   *  Destructor
+   */
   ~FaultTree();
   std::string getRoot();
 
-
+  /**
+   *  Function returns cut sets at the given point
+   *  NOTE
+   *    If MOCUS ran before this function call, min cut sets will be returned
+   */
   set_string getCutSets();
 
-
+  /**
+   *  Builds m-ary fault tree
+   */
   std::map<std::string, _node *> buildTree(Parser parser);
 
+  /**
+   *  Computes minimum cut sets based on MOCUS Algorithm
+   */
   set_string computeMinimumCutSets();
   std::vector<std::string> event(std::map<std::string, _node *>);
 
 private:
+  // Hash map for operators
   std::map<std::string, _operator_t> _opDict = {{"AND", AND}, {"OR", OR}};
+  // Inverse mapping for printing purpose only
   std::map<_operator_t, std::string> _opDictInv = {{AND, "AND"}, {OR, "OR"}};
   std::map<std::string, _node *> _node_d_b;
   std::string _root;
 
+  // Cut sets container for in-place computations
   set_string _sets;
 
+  /**
+   *  Translates string to opeartor
+   */
   _operator_t str2Operator(std::string op);
   void rmSets();
   _node * getNode(std::string name);
 
-
+  /**
+   *  Recursive call function to flood fill sets by expanding them based on
+   *  operation ALGO
+   *    1. Iterate through entire list and match for own node's name
+   *    2. Replace self with children based on operation
+   *         (i) . Replace self with children in same row if AND
+   *         (ii). Replace self with child one per row if OR
+   *    3. Recurse on each non leaf child
+   *
+   *  NOTE
+   *    1. Updates "sets" variable
+   *    2. Uses std::set 2d array, hence absorption and idempotence properties
+   *       are implicit
+   */
   void cutSetsExpand(_node * node);
   void removeSubsets();
 };
 
+/************************** Parser Definition **************************/
 
 class FTAUtils::Parser
 {
 public:
+  // Supported formats for parsing
   enum parseFormatT
   {
     FORMAT_CSV,
     FORMAT_UNDEF
   };
 
-
+  /**
+   *  Constructor for parser class
+   */
   Parser(std::string fileName, parseFormatT format);
 
+  /**
+   * Destructor for parser class
+   */
   ~Parser();
 
-
+  /**
+   *  Yields all records, populates the standard structure and returns
+   *  This function acts as an abstract layer to hide different formats
+   *  that might be supported in future
+   *
+   *  Returns: Array of strings
+   */
   vector_string yieldLines();
 
-
+  /**
+   *  Yields a single record, populates the standard structure and returns
+   *  This function acts as an abstract layer to hide different formats
+   *  that might be supported in future
+   *
+   *  Returns: Array of strings
+   */
   std::vector<std::string> yieldLine();
 
 private:
-
+  // Handle to file
   std::ifstream * fileP;
 };
 
@@ -124,4 +189,4 @@ class FTAUtils::CException
   CException(std::string s) : msg(s) {}
 };
 
-#endif
+#endif // _FAULT_TREE_H