[gardening] Refactor and rename some internal methods for clarity

* Split up setting calculation by language to match the flow of the
  implementation

* Rename the internal setting methods for consistency and clarity

* Add a few more doc comments

* Formatting cleanup around the code that was touched

Author: benlangmuir

Sources/SKSwiftPMWorkspace/SwiftPMWorkspace.swift

@@ -230,7 +230,7 @@ extension SwiftPMWorkspace: BuildSystem {
     }
 
     if path.basename == "Package.swift" {
-      return packageDescriptionSettings(path)
+      return settings(forPackageManifest: path)
     }
 
     if path.extension == "h" {
@@ -245,106 +245,26 @@ extension SwiftPMWorkspace {
 
   // MARK: Implementation details
 
+  /// Retrieve settings for the given file, which is part of a known target build description.
   public func settings(
     for path: AbsolutePath,
     _ language: Language,
-    _ td: TargetBuildDescription
-  ) -> FileBuildSettings? {
-
-    let buildPath = self.buildPath
-
+    _ td: TargetBuildDescription) -> FileBuildSettings?
+  {
     switch (td, language) {
     case (.swift(let td), .swift):
-      // FIXME: this is re-implementing llbuild's constructCommandLineArgs.
-      var args: [String] = [
-        "-module-name",
-        td.target.c99name,
-        "-incremental",
-        "-emit-dependencies",
-        "-emit-module",
-        "-emit-module-path",
-        buildPath.appending(component: "\(td.target.c99name).swiftmodule").asString,
-        // -output-file-map <path>
-      ]
-      if td.target.type == .library || td.target.type == .test {
-        args += ["-parse-as-library"]
-      }
-      args += ["-c"]
-      args += td.target.sources.paths.map{ $0.asString }
-      args += ["-I", buildPath.asString]
-      args += td.compileArguments()
-
-      return FileBuildSettings(
-        preferredToolchain: nil,
-        compilerArguments: args,
-        workingDirectory: workspacePath.asString
-      )
-
+      return settings(forSwiftFile: path, td)
     case (.clang, .swift):
       return nil
-
     case (.clang(let td), _):
-      // FIXME: this is re-implementing things from swiftpm's createClangCompileTarget
-
-      let compilePath = td.compilePaths().first(where: { $0.source == path })
-
-      var args = td.basicArguments()
-
-      if let compilePath = compilePath {
-        args += [
-          "-MD",
-          "-MT",
-          "dependencies",
-          "-MF",
-          compilePath.deps.asString,
-        ]
-      }
-
-      switch language {
-      case .c:
-        if let std = td.clangTarget.cLanguageStandard {
-          args += ["-std=\(std)"]
-        }
-      case .cpp:
-        if let std = td.clangTarget.cxxLanguageStandard {
-          args += ["-std=\(std)"]
-        }
-      default:
-        break
-      }
-
-      if let compilePath = compilePath {
-        args += [
-          "-c",
-          compilePath.source.asString,
-          "-o",
-          compilePath.object.asString
-        ]
-      } else if path.extension == "h" {
-        args += ["-c"]
-        if let xflag = language.xflagHeader {
-          args += ["-x", xflag]
-        }
-        args += [path.asString]
-      } else {
-        args += [
-          "-c",
-          path.asString,
-        ]
-      }
-
-      return FileBuildSettings(
-        preferredToolchain: nil,
-        compilerArguments: args,
-        workingDirectory: workspacePath.asString
-      )
-
+      return settings(forClangFile: path, language, td)
     default:
       return nil
     }
   }
 
-  func packageDescriptionSettings(_ path: AbsolutePath) -> FileBuildSettings? {
+  /// Retrieve settings for a package manifest (Package.swift).
+  func settings(forPackageManifest path: AbsolutePath) -> FileBuildSettings? {
     for package in packageGraph.packages where path == package.manifest.path {
         let compilerArgs = workspace.interpreterFlags(for: package.path) + [path.asString]
         return FileBuildSettings(
@@ -355,6 +275,7 @@ extension SwiftPMWorkspace {
     return nil
   }
 
+  /// Retrieve settings for a given header file.
   public func settings(forHeader path: AbsolutePath, _ language: Language) -> FileBuildSettings? {
     var dir = path.parentDirectory
     while !dir.isRoot {
@@ -365,8 +286,105 @@ extension SwiftPMWorkspace {
     }
     return nil
   }
+
+  /// Retrieve settings for the given swift file, which is part of a known target build description.
+  public func settings(
+    forSwiftFile path: AbsolutePath,
+    _ td: SwiftTargetBuildDescription) -> FileBuildSettings?
+  {
+    // FIXME: this is re-implementing llbuild's constructCommandLineArgs.
+    var args: [String] = [
+      "-module-name",
+      td.target.c99name,
+      "-incremental",
+      "-emit-dependencies",
+      "-emit-module",
+      "-emit-module-path",
+      buildPath.appending(component: "\(td.target.c99name).swiftmodule").asString,
+      // -output-file-map <path>
+    ]
+    if td.target.type == .library || td.target.type == .test {
+      args += ["-parse-as-library"]
+    }
+    args += ["-c"]
+    args += td.target.sources.paths.map { $0.asString }
+    args += ["-I", buildPath.asString]
+    args += td.compileArguments()
+
+    return FileBuildSettings(
+      preferredToolchain: nil,
+      compilerArguments: args,
+      workingDirectory: workspacePath.asString)
+  }
+
+  /// Retrieve settings for the given C-family language file, which is part of a known target build
+  /// description.
+  ///
+  /// - Note: language must be a C-family language.
+  public func settings(
+    forClangFile path: AbsolutePath,
+    _ language: Language,
+    _ td: ClangTargetBuildDescription) -> FileBuildSettings?
+  {
+    // FIXME: this is re-implementing things from swiftpm's createClangCompileTarget
+
+    var args = td.basicArguments()
+
+    let compilePath = td.compilePaths().first(where: { $0.source == path })
+    if let compilePath = compilePath {
+      args += [
+        "-MD",
+        "-MT",
+        "dependencies",
+        "-MF",
+        compilePath.deps.asString,
+      ]
+    }
+
+    switch language {
+    case .c:
+      if let std = td.clangTarget.cLanguageStandard {
+        args += ["-std=\(std)"]
+      }
+    case .cpp:
+      if let std = td.clangTarget.cxxLanguageStandard {
+        args += ["-std=\(std)"]
+      }
+    default:
+      break
+    }
+
+    if let compilePath = compilePath {
+      args += [
+        "-c",
+        compilePath.source.asString,
+        "-o",
+        compilePath.object.asString
+      ]
+    } else if path.extension == "h" {
+      args += ["-c"]
+      if let xflag = language.xflagHeader {
+        args += ["-x", xflag]
+      }
+      args += [path.asString]
+    } else {
+      args += [
+        "-c",
+        path.asString,
+      ]
+    }
+
+    return FileBuildSettings(
+      preferredToolchain: nil,
+      compilerArguments: args,
+      workingDirectory: workspacePath.asString)
+  }
 }
 
+/// A SwiftPM-compatible toolchain.
+///
+/// Appropriate for both building a pacakge (Build.Toolchain) and for loading the package manifest
+/// (ManifestResourceProvider).
 private struct SwiftPMToolchain: Build.Toolchain, ManifestResourceProvider {
   var swiftCompiler: AbsolutePath
   var clangCompiler: AbsolutePath
@@ -410,9 +428,12 @@ extension ToolchainRegistry {
   }
 }
 
-private func findPackageDirectory(containing path: AbsolutePath, _ fs: FileSystem) -> AbsolutePath? {
+/// Find a Swift Package root directory that contains the given path, if any.
+private func findPackageDirectory(
+  containing path: AbsolutePath,
+  _ fileSystem: FileSystem) -> AbsolutePath? {
   var path = path
-  while !fs.isFile(path.appending(component: "Package.swift")) {
+  while !fileSystem.isFile(path.appending(component: "Package.swift")) {
     if path.isRoot {
       return nil
     }
@@ -422,23 +443,21 @@ private func findPackageDirectory(containing path: AbsolutePath, _ fs: FileSyste
 }
 
 public final class BuildSettingProviderWorkspaceDelegate: WorkspaceDelegate {
-  public func packageGraphWillLoad(currentGraph: PackageGraph, dependencies: AnySequence<ManagedDependency>, missingURLs: Set<String>) {
-  }
+  public func packageGraphWillLoad(
+    currentGraph: PackageGraph,
+    dependencies: AnySequence<ManagedDependency>,
+    missingURLs: Set<String>)
+  {}
 
-  public func fetchingWillBegin(repository: String) {
-  }
+  public func fetchingWillBegin(repository: String) {}
 
-  public func fetchingDidFinish(repository: String, diagnostic: Basic.Diagnostic?) {
-  }
+  public func fetchingDidFinish(repository: String, diagnostic: Basic.Diagnostic?) {}
 
-  public func cloning(repository: String) {
-  }
+  public func cloning(repository: String) {}
 
-  public func removing(repository: String) {
-  }
+  public func removing(repository: String) {}
 
-  public func managedDependenciesDidUpdate(_ dependencies: AnySequence<ManagedDependency>) {
-  }
+  public func managedDependenciesDidUpdate(_ dependencies: AnySequence<ManagedDependency>) {}
 }
 
 extension Basic.Diagnostic.Behavior {