assorted code improvement

internal/zinc-scripted/src/test/scala/sbt/internal/inc/IncHandler.scala

@@ -208,12 +208,18 @@ class IncHandler(directory: Path, cacheDir: Path, scriptedLog: ManagedLogger, co
     new AnalyzingCompiler(instance, bridgeProvider, classpath, unit, IncHandler.classLoaderCache)
   }
 
+  // hopefully the meaning of the commands can be understood by looking at examples.
+  // the `check-recompilations` test is a good one for seeing how `checkDependencies`
+  // and `checkRecompilations` work.
   lazy val commands: Map[String, IncCommand] = Map(
     noArgs("compile") { case (p, i) => p.compile(i).map(_ => ()) },
     noArgs("clean") { case (p, _)   => p.clean() },
     onArgs("checkIterations") {
       case (p, x :: Nil, i) => p.checkNumberOfCompilerIterations(i, x.toInt)
     },
+    // note that this can only tell us the *last* round a class got compiled in.
+    // it can't tell us *every* round something got compiled in, since only
+    // still-extant classfiles are available for inspection
     onArgs("checkRecompilations") {
       case (p, step :: classNames, i) => p.checkRecompilations(i, step.toInt, classNames)
     },

zinc/src/sbt-test/source-dependencies/check-recompilations/test

@@ -1,9 +1,45 @@
+# this was the first checkRecompilations test ever written. it's a good
+# one for understanding how checkDependencies and checkRecompilations
+# are used.
+
+# the first compile command causes round 0 to happen
+
 > compile
 
+# every class gets compiled.
+
+> checkRecompilations 0 A B C D
+
+# now zinc knows the dependency relations between the classes:
+# ┌─┐┌─┐
+# │D││B│
+# └┬┘└┬┘
+# ┌▽┐ │
+# │C│ │
+# └┬┘ │
+# ┌▽──▽┐
+# │A   │
+# └────┘
+
+> checkDependencies A:
+> checkDependencies B: A
+> checkDependencies C: A
+> checkDependencies D: C
+
+# next, we swap in changed code
+
 $ copy-file changes/A.scala A.scala
 
+# the second compile command causes rounds 1, 2, and 3 to happen
+
 > compile
 
+# checkRecompilations only knows the *last* round in which something
+# got compiled. it doesn't know *all* the rounds when something got
+# compiled.  so that's why `checkRecompilations 0` is now empty.
+# after rounds 1, 2, and 3 have all finished, none of the classfiles
+# from round 0 are still extant.
+
 > checkRecompilations 0
 > checkRecompilations 1 A
 > checkRecompilations 2 B C

zinc/src/sbt-test/source-dependencies/class-based-inheritance/test

@@ -8,9 +8,12 @@
 
 # introduces first compile iteration
 > compile
+> checkRecompilations 0 A A2 B C
 $ copy-file changes/A1.scala src/main/scala/A.scala
 # second iteration and third iteration (due to invalidation of C)
 > compile
+> checkRecompilations 1 A A.AA A2
+> checkRecompilations 2 C
 $ copy-file changes/A2.scala src/main/scala/A.scala
 # fourth iteration
 > compile