RequirementMachine: Some comments

Author: slavapestov

lib/AST/RequirementMachine/GeneratingConformances.cpp

@@ -52,6 +52,11 @@ using namespace rewriting;
 /// Finds all protocol conformance rules appearing in a 3-cell, both without
 /// context, and with a non-empty left context. Applications of rules with a
 /// non-empty right context are ignored.
+///
+/// The rules are organized by protocol. For each protocol, the first element
+/// of the pair stores conformance rules that appear without context. The
+/// second element of the pair stores rules that appear with non-empty left
+/// context. For each such rule, the left prefix is also stored alongside.
 void HomotopyGenerator::findProtocolConformanceRules(
     llvm::SmallDenseMap<const ProtocolDecl *,
                         std::pair<SmallVector<unsigned, 2>,

lib/AST/RequirementMachine/RequirementMachine.cpp

@@ -369,6 +369,10 @@ RequirementMachine::RequirementMachine(RewriteContext &ctx)
 
 RequirementMachine::~RequirementMachine() {}
 
+/// Build a requirement machine for the requirements of a generic signature.
+///
+/// This must only be called exactly once, before any other operations are
+/// performed on this requirement machine.
 void RequirementMachine::initWithGenericSignature(CanGenericSignature sig) {
   Sig = sig;
 
@@ -404,6 +408,12 @@ void RequirementMachine::initWithGenericSignature(CanGenericSignature sig) {
   }
 }
 
+/// Build a requirement machine for the structural requirements of a set
+/// of protocols, which are understood to form a strongly-connected component
+/// (SCC) of the protocol dependency graph.
+///
+/// This must only be called exactly once, before any other operations are
+/// performed on this requirement machine.
 void RequirementMachine::initWithProtocols(ArrayRef<const ProtocolDecl *> protos) {
   Protos = protos;
 

lib/AST/RequirementMachine/RewriteContext.cpp

@@ -382,6 +382,8 @@ bool RewriteContext::isRecursivelyConstructingRequirementMachine(
   return !found->second->isComplete();
 }
 
+/// Implement Tarjan's algorithm to compute strongly-connected components in
+/// the protocol dependency graph.
 void RewriteContext::getRequirementMachineRec(
     const ProtocolDecl *proto,
     SmallVectorImpl<const ProtocolDecl *> &stack) {
@@ -453,6 +455,8 @@ void RewriteContext::getRequirementMachineRec(
   }
 }
 
+/// Lazily construct a requirement machine for the given protocol's strongly
+/// connected component (SCC) in the protocol dependency graph.
 RequirementMachine *RewriteContext::getRequirementMachine(
     const ProtocolDecl *proto) {
   auto found = Protos.find(proto);
@@ -471,6 +475,8 @@ RequirementMachine *RewriteContext::getRequirementMachine(
   auto *&machine = component.Machine;
 
   if (machine) {
+    // If this component has a machine already, make sure it is ready
+    // for use.
     if (!machine->isComplete()) {
       llvm::errs() << "Re-entrant construction of requirement "
                    << "machine for:";
@@ -479,6 +485,8 @@ RequirementMachine *RewriteContext::getRequirementMachine(
       abort();
     }
   } else {
+    // Construct a requirement machine from the structural requirements of
+    // the given set of protocols.
     machine = new RequirementMachine(*this);
     machine->initWithProtocols(component.Protos);
   }