Address review comments.

Author: David Ungar

Sources/SwiftDriver/IncrementalCompilation/ModuleDependencyGraph.swift

@@ -54,19 +54,19 @@ import SwiftOptions
     self.creationPhase = phase
   }
 
-  @_spi(Testing) public func getRequiredSource(for input: TypedVirtualPath,
-                                               function: String = #function,
-                                               file: String = #file,
-                                               line: Int = #line) -> DependencySource {
-    guard let source = inputDependencySourceMap.getSourceIfKnown(for: input)
+  @_spi(Testing) public func source(requiredFor input: TypedVirtualPath,
+                                    function: String = #function,
+                                    file: String = #file,
+                                    line: Int = #line) -> DependencySource {
+    guard let source = inputDependencySourceMap.sourceIfKnown(for: input)
     else {
       fatalError("\(input.file.basename) not found in inputDependencySourceMap, \(file):\(line) in \(function)")
     }
     return source
   }
 
-  @_spi(Testing) public func getNeededInput(for source: DependencySource) -> TypedVirtualPath? {
-    guard let input = inputDependencySourceMap.getInputIfKnown(for: source)
+  @_spi(Testing) public func input(neededFor source: DependencySource) -> TypedVirtualPath? {
+    guard let input = inputDependencySourceMap.input(ifKnownFor: source)
     else {
       info.diagnosticEngine.emit(warning: "Failed to find source file for '\(source.file.basename)', recovering with a full rebuild. Next build will be incremental.")
       return nil
@@ -141,7 +141,7 @@ extension ModuleDependencyGraph {
       return TransitivelyInvalidatedInputSet()
     }
     return collectInputsRequiringCompilationAfterProcessing(
-      dependencySource: getRequiredSource(for: input))
+      dependencySource: source(requiredFor: input))
   }
 }
 
@@ -163,14 +163,14 @@ extension ModuleDependencyGraph {
   /// speculatively scheduled in the first wave.
   func collectInputsInvalidatedBy(input: TypedVirtualPath
   ) -> TransitivelyInvalidatedInputArray {
-    let changedSource = getRequiredSource(for: input)
+    let changedSource = source(requiredFor: input)
     let allDependencySourcesToRecompile =
       collectSwiftDepsUsing(dependencySource: changedSource)
 
     return allDependencySourcesToRecompile.compactMap {
       depedencySource in
       guard depedencySource != changedSource else {return nil}
-      let dependentInput = inputDependencySourceMap.getInputIfKnown(for: depedencySource)
+      let dependentInput = inputDependencySourceMap.input(ifKnownFor: depedencySource)
       info.reporter?.report(
         "Found dependent of \(input.file.basename):", dependentInput)
       return dependentInput
@@ -190,7 +190,7 @@ extension ModuleDependencyGraph {
   /// Does the graph contain any dependency nodes for a given source-code file?
   func containsNodes(forSourceFile file: TypedVirtualPath) -> Bool {
     precondition(file.type == .swift)
-    guard let source = inputDependencySourceMap.getSourceIfKnown(for: file) else {
+    guard let source = inputDependencySourceMap.sourceIfKnown(for: file) else {
       return false
     }
     return containsNodes(forDependencySource: source)
@@ -203,7 +203,7 @@ extension ModuleDependencyGraph {
 
   /// Returns: false on error
   func populateInputDependencySourceMap(
-    `for` purpose: InputDependencySourceMap.AdditionPurpose
+    for purpose: InputDependencySourceMap.AdditionPurpose
   ) -> Bool {
     let ofm = info.outputFileMap
     let diags = info.diagnosticEngine
@@ -250,7 +250,7 @@ extension ModuleDependencyGraph {
   func collectInputsRequiringCompilation(byCompiling input: TypedVirtualPath
   ) -> TransitivelyInvalidatedInputSet? {
     precondition(input.type == .swift)
-    let dependencySource = getRequiredSource(for: input)
+    let dependencySource = source(requiredFor: input)
     return collectInputsRequiringCompilationAfterProcessing(
       dependencySource: dependencySource)
   }
@@ -345,7 +345,7 @@ extension ModuleDependencyGraph {
   ) -> TransitivelyInvalidatedInputSet? {
     var invalidatedInputs = TransitivelyInvalidatedInputSet()
     for invalidatedSwiftDeps in collectSwiftDepsUsingInvalidated(nodes: directlyInvalidatedNodes) {
-      guard let invalidatedInput = getNeededInput(for: invalidatedSwiftDeps)
+      guard let invalidatedInput = input(neededFor: invalidatedSwiftDeps)
       else {
         return nil
       }

Sources/SwiftDriver/IncrementalCompilation/ModuleDependencyGraphParts/InputDependencySourceMap.swift

@@ -11,6 +11,8 @@
 import Foundation
 import TSCBasic
 
+/// Maps input source files to- and from- `DependencySource`s containing the swiftdeps paths.
+/// Deliberately at the level of specific intention, for clarity and to facilitate restructuring later.
 @_spi(Testing) public struct InputDependencySourceMap: Equatable {
 
   /// Maps input files (e.g. .swift) to and from the DependencySource object.
@@ -26,21 +28,33 @@ import TSCBasic
   // replaced by a multi-map from swift files to dependency sources,
   // and a regular map from dependency sources to swift files -
   // since that direction really is one-to-one.
-  
+
+  /// Holds the mapping for now. To be replaced later.
   public typealias BiMap = BidirectionalMap<TypedVirtualPath, DependencySource>
   @_spi(Testing) public var biMap = BiMap()
 }
 
 // MARK: - Accessing
 extension InputDependencySourceMap {
-  @_spi(Testing) public func getSourceIfKnown(for input: TypedVirtualPath) -> DependencySource? {
+  /// Find where the swiftdeps are stored for a given source file.
+  ///
+  /// - Parameter input: A source file path
+  /// - Returns: the corresponding `DependencySource`, or nil if none known.
+  @_spi(Testing) public func sourceIfKnown(for input: TypedVirtualPath) -> DependencySource? {
     biMap[input]
   }
 
-  @_spi(Testing) public func getInputIfKnown(for source: DependencySource) -> TypedVirtualPath? {
+  /// Find where the source file is for a given swiftdeps file.
+  ///
+  /// - Parameter source: A `DependencySource` (containing a swiftdeps file)
+  /// - Returns: the corresponding input source file, or nil if none known.
+  @_spi(Testing) public func input(ifKnownFor source: DependencySource) -> TypedVirtualPath? {
     biMap[source]
   }
 
+  /// Enumerate the input <-> dependency source pairs to be serialized
+  ///
+  /// - Parameter eachFn: a function to be called for each pair
   @_spi(Testing) public func enumerateToSerializePriors(
     _ eachFn: (TypedVirtualPath, DependencySource) -> Void
   ) {
@@ -50,14 +64,29 @@ extension InputDependencySourceMap {
 
 // MARK: - Populating
 extension InputDependencySourceMap {
+  /// For structural modifications-to-come, reify the various reasons to add an entry.
   public enum AdditionPurpose {
-    case mocking,
-         buildingFromSwiftDeps,
-         readingPriors,
-         inputsAddedSincePriors }
+    /// For unit testing
+    case mocking
+
+    /// When building a graph from swiftDeps files without priors
+    case buildingFromSwiftDeps
+
+    /// Deserializing the map stored with the priors
+    case readingPriors
+
+    /// After reading the priors, used to add entries for any inputs that might not have been in the priors.
+    case inputsAddedSincePriors
+  }
+
+  /// Add a mapping to & from input source file to swiftDeps file path
+  ///
+  /// - Parameter input: the source file path
+  /// - Parameter dependencySource: the dependency source (holding the swiftdeps path)
+  /// - Parameter why: the purpose for this addition. Will be used for future restructuring.
   @_spi(Testing) public mutating func addEntry(_ input: TypedVirtualPath,
                                                _ dependencySource: DependencySource,
-                                               `for` _ : AdditionPurpose) {
+                                               for why: AdditionPurpose) {
     assert(input.type == .swift && dependencySource.typedFile.type == .swiftDeps)
     biMap[input] = dependencySource
   }

Sources/SwiftDriver/IncrementalCompilation/ModuleDependencyGraphParts/Tracer.swift

@@ -121,7 +121,7 @@ extension ModuleDependencyGraph.Tracer {
         path.compactMap { node in
           node.dependencySource.map {
             source in
-            graph.inputDependencySourceMap.getInputIfKnown(for: source).map {
+            graph.inputDependencySourceMap.input(ifKnownFor: source).map {
               input in
               "\(node.key) in \(input.file.basename)"
             }