Address review about doc blocks

Author: alexcrichton

src/cargo/core/compiler/build_context/mod.rs

@@ -31,15 +31,24 @@ pub struct BuildContext<'a, 'cfg> {
     pub extra_compiler_args: HashMap<Unit<'a>, Vec<String>>,
     pub packages: &'a PackageSet<'cfg>,
 
-    /// Information about the compiler.
+    /// Source of interning new units as they're created.
+    pub units: &'a UnitInterner<'a>,
+
+    /// Information about the compiler that we've detected on the local system.
     pub rustc: Rustc,
-    /// Build information for the host arch.
+
+    /// Build information for the "host", which is information about when
+    /// `rustc` is invoked without a `--target` flag. This is used for
+    /// procedural macros, build scripts, etc.
     host_config: TargetConfig,
-    /// Build information for the target.
+    host_info: TargetInfo,
+
+    /// Build information for targets that we're building for. This will be
+    /// empty if the `--target` flag is not passed, and currently also only ever
+    /// has at most one entry, but eventually we'd like to support multi-target
+    /// builds with Cargo.
     target_config: HashMap<CompileTarget, TargetConfig>,
     target_info: HashMap<CompileTarget, TargetInfo>,
-    host_info: TargetInfo,
-    pub units: &'a UnitInterner<'a>,
 }
 
 impl<'a, 'cfg> BuildContext<'a, 'cfg> {

src/cargo/core/compiler/build_context/target_info.rs

@@ -36,7 +36,7 @@ pub struct TargetInfo {
     pub rustdocflags: Vec<String>,
 }
 
-/// CompileKind of each file generated by a Unit, part of `FileType`.
+/// Kind of each file generated by a Unit, part of `FileType`.
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub enum FileFlavor {
     /// Not a special file type.

src/cargo/core/compiler/compile_kind.rs

@@ -4,12 +4,21 @@ use crate::util::errors::{CargoResult, CargoResultExt};
 use serde::Serialize;
 use std::path::Path;
 
-/// Indicates whether an object is for the host architcture or the target architecture.
+/// Indicator for how a unit is being compiled.
 ///
-/// These will be the same unless cross-compiling.
+/// This is used primarily for organizing cross compilations vs host
+/// compilations, where cross compilations happen at the request of `--target`
+/// and host compilations happen for things like build scripts and procedural
+/// macros.
 #[derive(PartialEq, Eq, Hash, Debug, Clone, Copy, PartialOrd, Ord, Serialize)]
 pub enum CompileKind {
+    /// Attached to a unit that is compiled for the "host" system or otherwise
+    /// is compiled without a `--target` flag. This is used for procedural
+    /// macros and build scripts, or if the `--target` flag isn't passed.
     Host,
+
+    /// Attached to a unit to be compiled for a particular target. This is used
+    /// for units when the `--target` flag is passed.
     Target(CompileTarget),
 }
 
@@ -42,6 +51,23 @@ impl CompileKind {
     }
 }
 
+/// Abstraction for the representation of a compilation target that Cargo has.
+///
+/// Compilation targets are one of two things right now:
+///
+/// 1. A raw target string, like `x86_64-unknown-linux-gnu`.
+/// 2. The path to a JSON file, such as `/path/to/my-target.json`.
+///
+/// Raw target strings are typically dictated by `rustc` itself and represent
+/// built-in targets. Custom JSON files are somewhat unstable, but supported
+/// here in Cargo. Note that for JSON target files this `CompileTarget` stores a
+/// full canonicalized path to the target.
+///
+/// The main reason for this existence is to handle JSON target files where when
+/// we call rustc we pass full paths but when we use it for Cargo's purposes
+/// like naming directories or looking up configuration keys we only check the
+/// file stem of JSON target files. For built-in rustc targets this is just an
+/// uninterpreted string basically.
 #[derive(PartialEq, Eq, Hash, Debug, Clone, Copy, PartialOrd, Ord, Serialize)]
 pub struct CompileTarget {
     name: InternedString,
@@ -71,10 +97,22 @@ impl CompileTarget {
         Ok(CompileTarget { name: name.into() })
     }
 
+    /// Returns the full unqualified name of this target, suitable for passing
+    /// to `rustc` directly.
+    ///
+    /// Typically this is pretty much the same as `short_name`, but for the case
+    /// of JSON target files this will be a full canonicalized path name for the
+    /// current filesystem.
     pub fn rustc_target(&self) -> &str {
         &self.name
     }
 
+    /// Returns a "short" version of the target name suitable for usage within
+    /// Cargo for configuration and such.
+    ///
+    /// This is typically the same as `rustc_target`, or the full name, but for
+    /// JSON target files this returns just the file stem (e.g. `foo` out of
+    /// `foo.json`) instead of the full path.
     pub fn short_name(&self) -> &str {
         // Flexible target specifications often point at json files, so if it
         // looks like we've got one of those just use the file stem (the file

src/cargo/core/compiler/mod.rs

@@ -924,7 +924,7 @@ fn build_deps_args<'a, 'cfg>(
 
     // Be sure that the host path is also listed. This'll ensure that proc macro
     // dependencies are correctly found (for reexported macros).
-    if let CompileKind::Target(_) = unit.kind {
+    if !unit.kind.is_host() {
         cmd.arg("-L").arg(&{
             let mut deps = OsString::from("dependency=");
             deps.push(cx.files().host_deps());