Merge pull request #27 from haejinjo/addDocumentation

Add documentation to backend

Author: haejinjo

package.json

@@ -42,8 +42,12 @@
     "Ergi Shehu",
     "Gabriela Jardim Aquino",
     "Gregory Panciera",
+    "Haejin Jo",
+    "Hien Nguyen",
+    "Jack Crish",
     "Josh Kim",
     "Joshua Howard",
+    "Kevin Fey",
     "Nathanael Wa Mwenze",
     "Prasanna Malla",
     "Rajeeb Banstola",
@@ -128,4 +132,4 @@
     "recoil": "0.0.10",
     "sankey": "^2.0.2"
   }
-}
+}

src/app/__tests__/Chart_deprecated_.test.tsx

@@ -40,7 +40,7 @@ interface StateRouteProps {
 const StateRoute = (props: StateRouteProps) => {
   const { snapshot, hierarchy, snapshots, viewIndex } = props;
 
-  let isRecoil = snapshot.AtomsRelationship ? true : false;
+  const isRecoil = snapshot.AtomsRelationship ? true : false;
   const [noRenderData, setNoRenderData] = useState(false);
 
   // component map zoom state
@@ -50,29 +50,25 @@ const StateRoute = (props: StateRouteProps) => {
     k: 1,
   });
 
-  //Map
+  // Map
   const renderComponentMap = () => {
     if (hierarchy) {
       return <ComponentMap viewIndex={viewIndex} snapshots={snapshots} x={x} y={y} k={k} setZoomState={setZoomState} />;
     }
     return <div className="noState">{NO_STATE_MSG}</div>;
   };
 
-
   // the hierarchy gets set on the first click in the page
   // when the page is refreshed we may not have a hierarchy, so we need to check if hierarchy was initialized
   // if true involk render chart with hierarchy
   const renderHistory = () => {
     if (hierarchy.children.length > 0) {
-
       return <History hierarchy={hierarchy} />;
     }
-    return <div className="noState">Application not compatible with history</div>;
+    return <div className="noState">History graph will render on first state change</div>;
   };
 
-  const renderAtomsRelationship = () => {
-    return <AtomsRelationship atomsRel={snapshot.AtomsRelationship} />;
-  };
+  const renderAtomsRelationship = () => <AtomsRelationship atomsRel={snapshot.AtomsRelationship} />;
 
   // the hierarchy gets set on the first click in the page
   // when the page is refreshed we may not have a hierarchy, so we need to check if hierarchy was initialized
@@ -83,30 +79,16 @@ const StateRoute = (props: StateRouteProps) => {
     }
     return <div className="noState">{NO_STATE_MSG}</div>;
   };
-  
-  let perfChart;
-  if (true) {
-    
-    perfChart = (
-      <PerfView
-        viewIndex={viewIndex}
-        snapshots={snapshots}
-        setNoRenderData={setNoRenderData}
-        width={600}
-        height={1000}
-      />
-    );
-  }
-
-  //This will intermitently block Recoil PerfCharts from rendering
-  // else {
-  //   perfChart = (
-  //     <div className="no-data-message">
-  //       Application must be running in development mode in order to view
-  //       performance data
-  //     </div>
-  //   );
-  // }
+
+  const perfChart = (
+    <PerfView
+      viewIndex={viewIndex}
+      snapshots={snapshots}
+      setNoRenderData={setNoRenderData}
+      width={600}
+      height={1000}
+    />
+  );
 
   const renderPerfView = () => <ErrorHandler>{perfChart}</ErrorHandler>;
 
@@ -131,10 +113,13 @@ const StateRoute = (props: StateRouteProps) => {
         <NavLink className="router-link" activeClassName="is-active" to="/map">
           Map
         </NavLink>
-        
-        {isRecoil && <NavLink className="router-link" activeClassName="is-active" to="/relationship">
-        Relationships
-        </NavLink>}
+
+        {isRecoil
+          && (
+            <NavLink className="router-link" activeClassName="is-active" to="/relationship">
+              Relationships
+            </NavLink>
+          )}
 
         <NavLink
           className="router-link"

src/app/components/StateRoute.tsx

@@ -9,8 +9,6 @@
 // eslint-disable-next-line import/newline-after-import
 const acorn = require('acorn');
 const jsx = require('acorn-jsx');
-// import { acorn } from 'acorn'; // javascript parser
-// import { jsx } from 'acorn-jsx';
 
 const JSXParser = acorn.Parser.extend(jsx());
 
@@ -19,19 +17,37 @@ const JSXParser = acorn.Parser.extend(jsx());
  * @param f A function to throttle
  * @param t A number of milliseconds to use as throttling interval
  * @returns A function that limits input function, `f`, from being called more than once every `t` milliseconds
+ *
  */
 export const throttle = (f: Function, t: number): Function => {
-  let isOnCooldown: boolean = false;
-  let isCallQueued: boolean = false;
+  // Initialize boolean flags for callback, throttledFunc
+  let isOnCooldown = false;
+  let isCallQueued = false;
+
+  // Wrap the passed-in function, f, in a callback function that "throttles"
+  // (puts a limit on) the number of calls that can be made to function, f
+  // in a given period of time (ms), t
   const throttledFunc = (): any => {
+    // CASE 1: In cooldown mode and we already have a function waiting to be executed,
+    //         so do nothing
     if (isOnCooldown && isCallQueued) return;
+
+    // CASE 2: In cooldown mode, but we have no functions waiting to be executed,
+    //         so just make note that we now have a call waiting to be executed and return
     if (isOnCooldown) {
       isCallQueued = true;
       return;
     }
+
+    // CASE 3: If we are ready to "fire":
+    // Execute the function, f, immediately
     f();
+    // Initiate a new cooldown period and reset the "call queue"
     isOnCooldown = true;
     isCallQueued = false;
+
+    // Declare a function that checks whether we have
+    // another function to be executed right after.
     const runAfterTimeout = (): any => {
       if (isCallQueued) {
         isCallQueued = false;
@@ -42,59 +58,58 @@ export const throttle = (f: Function, t: number): Function => {
       }
       isOnCooldown = false;
     };
+
     setTimeout(runAfterTimeout, t);
   };
+
   return throttledFunc;
 };
 
 // Helper function to grab the getters/setters from `elementType`
-
 /**
  * @method getHooksNames
- * @param elementType The fiber (whose hooks we want) `type`, A stringified function of the component the Fiber whose hooks we want corresponds to
- * @returns An array of strings 
+ * @param elementType The fiber `type`, A stringified function of the component the Fiber whose hooks we want corresponds to
+ * @returns An array of strings
  */
 export const getHooksNames = (elementType: string): Array<string> => {
   // Initialize empty object to store the setters and getter
   let ast: any;
   try {
     ast = JSXParser.parse(elementType);
   } catch (e) {
-    console.error(`getHooksNames ERROR: Failed to parse elementType string:\n${elementType}`);
     return ['unknown'];
   }
 
   const hooksNames: any = {};
 
+  // Begin search for hook names, only if ast has a body property.
   while (Object.hasOwnProperty.call(ast, 'body')) {
-    let tsCount: number = 0; // Counter for the number of TypeScript hooks seen (to distinguish in masterState)
+    let tsCount = 0; // Counter for the number of TypeScript hooks seen (to distinguish in masterState)
     ast = ast.body;
-    const statements: Array<string> = [];
 
+    // Statements get all the names of the hooks. For example: useCount, useWildcard, ...
+    const statements: Array<string> = [];
     /** All module exports always start off as a single 'FunctionDeclaration' type
      * Other types: "BlockStatement" / "ExpressionStatement" / "ReturnStatement"
      * Iterate through AST of every function declaration
      * Check within each function declaration if there are hook declarations */
-    ast.forEach((functionDec) => {
+    ast.forEach(functionDec => {
       let body: any;
-      if (functionDec.expression && functionDec.expression.body)
-        body = functionDec.expression.body.body;
+      if (functionDec.expression && functionDec.expression.body) body = functionDec.expression.body.body;
       else body = functionDec.body ? functionDec.body.body : [];
       // Traverse through the function's funcDecs and Expression Statements
       body.forEach((elem: any) => {
+        // Hooks will always be contained in a variable declaration
         if (elem.type === 'VariableDeclaration') {
           elem.declarations.forEach((hook: any) => {
-            // * TypeScript hooks appear to have no "VariableDeclarator"
-            // * with id.name of _useState, _useState2, etc...
-            // * hook.id.type relevant for TypeScript applications
-            // *
-            // * Works for useState hooks
+            // Parse destructured statements pair
             if (hook.id.type === 'ArrayPattern') {
               hook.id.elements.forEach((hook) => {
                 statements.push(`_useWildcard${tsCount}`);
                 statements.push(hook.name);
                 tsCount += 1;
               });
+              // Process hook function invocation ?
             } else {
               if (hook.init.object && hook.init.object.name) {
                 const varName: any = hook.init.object.name;