Added some comments around incremental compilation.

Author: David Ungar

include/swift/Driver/DependencyGraph.h

@@ -121,6 +121,16 @@ class DependencyGraphImpl {
   llvm::StringMap<std::pair<std::vector<DependencyEntryTy>, DependencyMaskTy>> Dependencies;
 
   /// The set of marked nodes.
+  /// "Marked" means that everything provided by this node (i.e. Job) is
+  /// dirty. Thus any file using any of these provides must be recompiled.
+  /// (Only non-private entities are output as provides.)
+  /// In other words, this Job "cascades"; the need to recompile it causes other
+  /// recompilations. It is possible that the current code marks things that do
+  /// not need to be marked. Nothing would break if that were the case.
+  ///
+  /// "Marked" does NOT mean that any successors in the graph have been
+  /// processed. The traversal routines use "Visited" to avoid endless
+  /// "recursion".
   llvm::SmallPtrSet<const void *, 16> Marked;
 
   /// A list of all external dependencies that cannot be resolved from just this
@@ -153,6 +163,12 @@ class DependencyGraphImpl {
     (void)newlyInserted;
   }
 
+  /// Starting at \p node, visit the transitive closure of every dependent node.
+  /// Assume that the starting node is "cascading"; that all dependencies must
+  /// be dirty if the start is dirty. Therefore, mark the start. For each
+  /// visited node, add it to visited, and mark it if it cascades. The start
+  /// node is NOT added to visited.
+
   void markTransitive(SmallVectorImpl<const void *> &visited,
                       const void *node, MarkTracerImpl *tracer = nullptr);
   bool markIntransitive(const void *node) {

include/swift/Driver/Job.h

@@ -230,9 +230,17 @@ class CommandOutput {
 class Job {
 public:
   enum class Condition {
+    // There was no input map, or the map makred this Job as dirty
+    // but the input didn't change.
+    // Be maximally conservative with dependencies.
     Always,
+    // The input changed, or this job was private or [it was not dirty but
+    // primary output was missing].
     RunWithoutCascading,
+    // The best case: input didn't change, output exists.
+    // Only run if it depends on some other thing that changed.
     CheckDependencies,
+    // Pessimal: run no matter what.
     NewlyAdded
   };
 

lib/Driver/Compilation.cpp

@@ -206,8 +206,9 @@ namespace driver {
     /// Jobs that incremental-mode has decided it can skip.
     CommandSet DeferredCommands;
 
-    /// Jobs in the initial set with Condition::Always, or lacking existing
+    /// Jobs in the initial set with Condition::Always, and having an existing
     /// .swiftdeps files.
+    /// Set by scheduleInitialJobs and used only by scheduleAdditionalJobs.
     SmallVector<const Job *, 16> InitialOutOfDateCommands;
 
     /// Dependency graph for deciding which jobs are dirty (need running)
@@ -382,7 +383,7 @@ namespace driver {
       DeferredCommands.clear();
     }
 
-    /// Helper that attmepts to reload a job's .swiftdeps file after the job
+    /// Helper that attempts to reload a job's .swiftdeps file after the job
     /// exits, and re-run transitive marking to ensure everything is properly
     /// invalidated by any new dependency edges introduced by it. If reloading
     /// fails, this can cause deferred jobs to be immediately scheduled.
@@ -679,6 +680,11 @@ namespace driver {
     }
 
     /// Schedule all jobs we can from the initial list provided by Compilation.
+    ///
+    /// It would probably be safe and simpler to markTransitive on the start
+    /// nodes in the "Always" condition from the start instead of using
+    /// markIntransitive and having later functions call markTransitive. That
+    /// way markInstransitive would be an implemenation detail.
     void scheduleInitialJobs() {
       for (const Job *Cmd : Comp.getJobs()) {
         if (!Comp.getIncrementalBuildEnabled()) {
@@ -715,7 +721,9 @@ namespace driver {
         switch (Condition) {
         case Job::Condition::Always:
           if (Comp.getIncrementalBuildEnabled() && !DependenciesFile.empty()) {
+            // Ensure dependents will get recompiled.
             InitialOutOfDateCommands.push_back(Cmd);
+            // Mark this job as cascading.
             DepGraph.markIntransitive(Cmd);
           }
           LLVM_FALLTHROUGH;

lib/Driver/CompilationRecord.h

@@ -19,8 +19,8 @@ namespace swift {
 namespace driver {
 namespace compilation_record {
 
-/// Compilation record files (.swiftdeps files) are YAML files composed of these
-/// top-level keys.
+/// Compilation record files (-master.swiftdeps files) are YAML files composed
+/// of these top-level keys.
 enum class TopLevelKey {
   /// The key for the Swift compiler version used to produce the compilation
   /// record.