second comment pass - usage and defn

Author: kyleheadley

clang/include/clang/3C/3C.h

@@ -106,6 +106,7 @@ class _3CInterface {
 
   // Constraint Building.
 
+  // Create ConstraintVariables to hold constraints
   bool addVariables();
 
   // Build initial constraints.

clang/include/clang/3C/ConstraintVariables.h

@@ -379,6 +379,7 @@ class PointerVariableConstraint : public ConstraintVariable {
 
   const CAtoms &getCvars() const { return Vars; }
 
+  // Include new ConstAtoms, supplemental info, and merge function pointers
   void mergeDeclaration(ConstraintVariable *From, ProgramInfo &I,
                         std::string &ReasonFailed) override;
 
@@ -528,6 +529,7 @@ class FunctionVariableConstraint : public ConstraintVariable {
     return S->getKind() == FunctionVariable;
   }
 
+  // Merge return value and all params
   void mergeDeclaration(ConstraintVariable *FromCV, ProgramInfo &I,
                         std::string &ReasonFailed) override;
 

clang/include/clang/3C/ProgramInfo.h

@@ -178,6 +178,8 @@ class ProgramInfo : public ProgramVariableAdder {
   void specialCaseVarIntros(ValueDecl *D, ASTContext *Context);
 
   // Inserts the given FVConstraint set into the extern or static function map.
+  // Returns the merged version if it was a redeclaration, or the constraint
+  // parameter if it was new.
   FunctionVariableConstraint *
   insertNewFVConstraint(FunctionDecl *FD, FVConstraint *FVCon, ASTContext *C);
 

clang/lib/3C/ConstraintBuilder.cpp

@@ -619,12 +619,8 @@ void VariableAdderConsumer::HandleTranslationUnit(ASTContext &C) {
 
   VariableAdderVisitor VAV = VariableAdderVisitor(&C, Info);
   TranslationUnitDecl *TUD = C.getTranslationUnitDecl();
-  // Generate constraints.
+  // Collect Variables.
   for (const auto &D : TUD->decls()) {
-    // The order of these traversals CANNOT be changed because both the type
-    // variable and constraint gen visitor require that variables have been
-    // added to ProgramInfo, and the constraint gen visitor requires the type
-    // variable information gathered in the type variable traversal.
     VAV.TraverseDecl(D);
   }
 
@@ -657,6 +653,10 @@ void ConstraintBuilderConsumer::HandleTranslationUnit(ASTContext &C) {
 
   // Generate constraints.
   for (const auto &D : TUD->decls()) {
+    // The order of these traversals CANNOT be changed because the constraint
+    // gen visitor requires the type variable information gathered in the type
+    // variable traversal.
+
     CSBV.TraverseDecl(D);
     TV.TraverseDecl(D);
     GV.TraverseDecl(D);

clang/lib/3C/ProgramInfo.cpp

@@ -558,11 +558,9 @@ void ProgramInfo::addVariable(clang::DeclaratorDecl *D,
       return;
     }
 
-    // Store the FVConstraint in the global and Variables maps. In doing this,
-    // insertNewFVConstraint might replace the atoms in F with the atoms of a
-    // FVConstraint that already exists in the map. Doing this loses any
-    // constraints that might have effected the original atoms, so do not create
-    // any constraint on F before this function is called.
+    // Store the FVConstraint in the global and Variables maps. It may be
+    // merged with others if this is a redeclaration, and the merged version
+    // is returned.
     F = insertNewFVConstraint(FD, F, AstContext);
     NewCV = F;