cleaned up comments

src/V3UndrivenCapture.cpp

@@ -156,8 +156,7 @@ const std::vector<V3UndrivenCapture::Var>& V3UndrivenCapture::computeWriteSummar
         UINFO(DBG, "undriven capture recursion detected at "
                        << taskNameQ(taskp)
                        << " returning directWrites size=" << info.directWrites.size());
-        // Cycle detected. Simple behaviour:
+        // Cycle detected. return directWrites only to guarantee termination.
-        // return directWrites only to guarantee termination.
         if (info.writeSummary.empty()) info.writeSummary = info.directWrites;
         sortUniqueVars(info.writeSummary);
         return info.writeSummary;
@@ -168,18 +167,20 @@ const std::vector<V3UndrivenCapture::Var>& V3UndrivenCapture::computeWriteSummar
     // Start with direct writes
     info.writeSummary = info.directWrites;
 
-    // Union in callees
+    // Need callees
     for (FTask calleep : info.callees) {
         if (m_info.find(calleep) == m_info.end()) continue;
         const std::vector<Var>& sub = computeWriteSummary(calleep);
         info.writeSummary.insert(info.writeSummary.end(), sub.begin(), sub.end());
     }
 
+    // Remove duplicates and sort because grabbing all of the callees can result in duplicates
     sortUniqueVars(info.writeSummary);
 
     UINFO(DBG, "undriven capture writeSummary computed size=" << info.writeSummary.size()
                                                               << " for " << taskNameQ(taskp));
 
+    // We are done, so set the m_info state correctly and return the vector of variables
     info.state = State::DONE;
     return info.writeSummary;
 }

src/V3UndrivenCapture.h

@@ -32,6 +32,9 @@ public:
     using Var = AstVar*;
 
     // DFS computation state for writeSummary propagation.
+    // UNVISITED: write summary not computed yet
+    // VISITING: currently computing on the call stack - used to detect cycles
+    // DONE: write summary computed
     enum class State : uint8_t { UNVISITED, VISITING, DONE };
 
     struct FTaskInfo final {
@@ -39,24 +42,25 @@ public:
         std::vector<Var> directWrites;
         // Direct resolved callees from this task/function body.
         std::vector<FTask> callees;
-        // 'write through write' writeSummary for the given task/function.
+        // 'write through write' writeSummary for the given task/function.  Meaning ultimately everything that this function/task writes to.
         std::vector<Var> writeSummary;
         // state for writeSummary computation.
         State state = State::UNVISITED;
     };
 
+    // Enable writeSummary computation.  If disabled, then the existing V3Undriven behaviour is used.
     static bool enableWriteSummary;
 
 private:
-    // Per-task/function capture info keyed by resolved AstNodeFTask* identity.
+    // Per-task/function capture info keyed by resolved AstNodeFTask* identity (FTask = function or task).  This is our 'graph' of tasks/functions.  Each node has a list of direct callees and a list of variables written in the function body.  There are methods to remove duplicates otherwise this could explode.
     std::unordered_map<FTask, FTaskInfo> m_info;
 
-    // Sort and remove duplicates from a vector of variables.
+    // Sort and remove duplicates from a vector of variables.  This is called after a task/function write summary is computed.  writeSummary can accumulate duplicates if a variable is written in multiple tasks/functions.
     static void sortUniqueVars(std::vector<Var>& vec);
-    // Sort and remove duplicates from a vector of callees.
+    // Sort and remove duplicates from a vector of callees.  The visitor can record the same callee multiple times (multiple call sites, branches, etc).
     static void sortUniqueFTasks(std::vector<FTask>& vec);
 
-    // Collect direct writes and call edges for all tasks/functions.
+    // Collect direct writes and call edges for all tasks/functions.  Run one time when UndrivenCapture is created.  This runs the visitor over the tree.
     void gather(AstNetlist* netlistp);
     // Compute (and cache) 'write through write' writeSummary for the given task/function.
     const std::vector<Var>& computeWriteSummary(FTask taskp);
@@ -65,18 +69,20 @@ public:
     // Build capture database and precompute writeSummary for all discovered tasks/functions.
     explicit V3UndrivenCapture(AstNetlist* netlistp);
 
-    // Lookup task/function capture info (nullptr if unknown).
+    // Lookup task/function capture info (nullptr if unknown).  This is currently only used for the debug helper.
     const FTaskInfo* find(FTask taskp) const;
-    // Get write through write through write, etc (call chain) writeSummary for a task/function
+    // Get write through write through write, etc (call chain) writeSummary for a task/function (creates empty entry if needed).  This returns a vector of variables that a particular task/function writes to, including all variables written by functions called by this task/function, and so on.
-    // (creates empty entry if needed).
     const std::vector<Var>& writeSummary(FTask taskp);
 
-    // used by the capture visitor
+    // used by the capture visitor to record information about tasks/functions and their statements and callees.
+    // noteTask() makes sure there is an entry for the given taskp.
     void noteTask(FTask taskp);
+    // inside the body of taskp there is a write to variable varp
     void noteDirectWrite(FTask taskp, Var varp);
+    // inside the body of callerp there is a call to calleep, this is needed so we can create a summary that includes all variables written by functions called by this task/function, and so on.
     void noteCallEdge(FTask callerp, FTask calleep);
 
-    // Optional: dump one task's summary (for debug bring-up).
+    // dump one task's summary for debugging.  leaving this in, in case need to debug future functionality.
     void debugDumpTask(FTask taskp, int level = 9) const;
 };