Reorganise code in IncrementalCommon and document it

While I was trying to implement some improvements here, I realize that
the current code can hardly be read and reused. I struggled as well to
understand the nitty-gritty of the algorithm as the control flow was not
clear and the order of functions was confusing.

This commit aims to fix this by reorganising the code to allow for more
reuse (functions in `IncrementalCommon`'s companion), reorganizes the
outline of `IncrementalCommon` to have clearer names and structure and
documents the most important parts of the code with implementation and
contract details.

internal/compiler-bridge/src/main/scala/xsbt/ExtractAPI.scala

@@ -431,8 +431,7 @@ class ExtractAPI[GlobalType <: Global](
     def mkVar = Some(fieldDef(in, sym, keepConst = false, xsbti.api.Var.of(_, _, _, _, _)))
     def mkVal = Some(fieldDef(in, sym, keepConst = true, xsbti.api.Val.of(_, _, _, _, _)))
     if (isClass(sym))
-      if (ignoreClass(sym)) {allNonLocalClassSymbols.+=(sym); None}
-      else Some(classLike(in, sym))
+      if (ignoreClass(sym)) { allNonLocalClassSymbols.+=(sym); None } else Some(classLike(in, sym))
     else if (sym.isNonClassType)
       Some(typeDef(in, sym))
     else if (sym.isVariable)

internal/zinc-core/src/main/scala/sbt/internal/inc/Incremental.scala

@@ -63,7 +63,7 @@ object Incremental {
     val previous = previous0 match { case a: Analysis => a }
     val incremental: IncrementalCommon =
       new IncrementalNameHashing(log, options)
-    val initialChanges = incremental.changedInitial(sources, previous, current, lookup)
+    val initialChanges = incremental.detectInitialChanges(sources, previous, current, lookup)
     val binaryChanges = new DependencyChanges {
       val modifiedBinaries = initialChanges.binaryDeps.toArray
       val modifiedClasses = initialChanges.external.allModified.toArray
@@ -118,15 +118,11 @@ object Incremental {
   private[inc] def apiDebug(options: IncOptions): Boolean =
     options.apiDebug || java.lang.Boolean.getBoolean(apiDebugProp)
 
-  private[sbt] def prune(invalidatedSrcs: Set[File], previous: CompileAnalysis): Analysis =
-    prune(invalidatedSrcs, previous, ClassFileManager.deleteImmediately)
-
-  private[sbt] def prune(invalidatedSrcs: Set[File],
-                         previous0: CompileAnalysis,
-                         classfileManager: XClassFileManager): Analysis = {
-    val previous = previous0 match { case a: Analysis => a }
-    classfileManager.delete(invalidatedSrcs.flatMap(previous.relations.products).toArray)
-    previous -- invalidatedSrcs
+  private[sbt] def prune(invalidatedSrcs: Set[File], previous0: CompileAnalysis): Analysis = {
+    val previous = previous0.asInstanceOf[Analysis]
+    IncrementalCommon.pruneClassFilesOfInvalidations(invalidatedSrcs,
+                                                     previous,
+                                                     ClassFileManager.deleteImmediately)
   }
 
   private[this] def manageClassfiles[T](options: IncOptions)(run: XClassFileManager => T): T = {