add some documentation to sema/lexer/parser and tc2halide

Author: prigoyal

tc/core/halide2isl.cc

@@ -34,7 +34,8 @@ using namespace tc::polyhedral::detail;
 
 SymbolTable makeSymbolTable(const tc2halide::HalideComponents& components) {
   // const Stmt& s) {
-  // Collect and categorize all the Variable symbols
+  // Collect and categorize all the Halide Variable symbols as reduction
+  // or index variables
   class BuildSymbolTable : public IRVisitor {
     using IRVisitor::visit;
     std::set<std::string> included;
@@ -59,7 +60,7 @@ SymbolTable makeSymbolTable(const tc2halide::HalideComponents& components) {
 
   components.stmt.accept(&builder);
   // Get params from components.params which contain everything declared in
-  // tcdef. However, the 0-D tensors are registered as both params and inputs,
+  // TC Def. However, the 0-D tensors are registered as both params and inputs,
   // filter those out.
   for (auto kvp : components.params) {
     bool skip = false;

tc/core/tc2halide.cc

@@ -62,10 +62,13 @@ Type translateScalarType(int tcType) {
   }
 }
 
+// Translate the TC def input params to corresponding Halide components.
+// params, inputs will be populated here.
 void translateParam(
     const lang::Param& p,
     map<string, Parameter>* params,
     vector<ImageParam>* inputs) {
+  // Check if the param has already been converted to halide components.
   if (params->find(p.ident().name()) != params->end()) {
     return;
   } else {
@@ -488,6 +491,9 @@ Expr reductionUpdate(Expr e) {
   return Call::make(e.type(), kReductionUpdate, {e}, Call::Intrinsic);
 }
 
+// Translate a single TC comprehension/statement to Halide components: funcs,
+// bounds, reductions.
+//
 // Note that the function definitions created by translateComprehension may
 // contain kReductionUpdate intrinsics.  These may have to be removed
 // in order to be able to apply internal Halide analysis passes on them.
@@ -736,6 +742,7 @@ void translateComprehension(
   stage.reorder(loop_nest);
 }
 
+// Translate a semantically checked TC def to HalideComponents struct.
 HalideComponents translateDef(const lang::Def& def, bool throwWarnings) {
   map<string, Function> funcs;
   HalideComponents components;
@@ -895,6 +902,8 @@ translate(isl::ctx ctx, const lang::TreeRef& treeRef, bool throwWarnings) {
       lang::Def(lang::Sema().checkFunction(treeRef)), throwWarnings);
 }
 
+// NOTE: there is no guarantee here that the tc string has only one def. It
+// could have many defs. Only first def will be converted in that case.
 HalideComponents
 translate(isl::ctx ctx, const std::string& tc, bool throwWarnings) {
   LOG_IF(INFO, tc::FLAGS_debug_halide) << tc;

tc/core/tc2halide.h

@@ -27,8 +27,8 @@ namespace tc2halide {
 // of the input and output tensors. We do not explicitly enumerate the
 // scalar params.
 struct HalideComponents {
-  lang::TreeRef
-      def; // post-semantic analaysis tree, used for later error reporting
+  // post-semantic analaysis tree, used for later error reporting
+  lang::TreeRef def;
   Halide::Internal::Stmt stmt;
   std::vector<Halide::ImageParam> inputs;
   std::map<std::string, Halide::Internal::Parameter> params;

tc/lang/sema.h

@@ -339,6 +339,21 @@ struct Sema {
         throw ErrorReport(exp) << "NYI - semantic checking for " << exp;
     }
   }
+  // This is the entry function for semantic analysis. It is called by
+  // tc2halide to associate type with each node of the tree and to also make
+  // sure that the tree is sematically correct. For example: a variable
+  // may not be input two times. Parser only verifies for the syntax but does
+  // not check the semantics.
+  //
+  // It converts the TK_APPLY nodes to TK_ACCESS or TK_BUILT_IN
+  //
+  // The reduction variables are deduced and the objects are created for them
+  // and they are appended to the tree
+  //
+  // Type checking is also done by small amount of code
+  //
+  // The method 'withType' can be used to associate the type with a given node
+  //
   TreeRef checkFunction(TreeRef func_) {
     auto func = Def(func_);
     auto params_ =
@@ -350,6 +365,10 @@ struct Sema {
       }
     }
 
+    // Everything has to be input or output. Keep track of the variables that
+    // are either input/output. We will check that the statements have variables
+    // from this list. If not, then throw error that temporaries are not yet
+    // implemented.
     for (auto p : func.params()) {
       nonTemporaries.insert(p.ident().name());
       inputParameters.insert(p.ident().name());
@@ -437,6 +456,7 @@ struct Sema {
       return checkRangeConstraint(RangeConstraint(ref));
     }
   }
+  // Semantic checking for the statements/comprehensions in a TC Def.
   TreeRef checkStmt(TreeRef stmt_) {
     auto stmt = Comprehension(stmt_);