doc(context): more docs and intra-doc links

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

@@ -40,6 +40,8 @@ pub use self::target_info::{
 /// since it is often too lower-level.
 /// Instead, [`ops::create_bcx`] is usually what you are looking for.
 ///
+/// After a `BuildContext` is built, the next stage of building is handled in [`Context`].
+///
 /// [`Context`]: crate::core::compiler::Context
 /// [`ops::create_bcx`]: crate::ops::create_bcx
 pub struct BuildContext<'a, 'cfg> {

src/cargo/core/compiler/context/compilation_files.rs

@@ -1,3 +1,5 @@
+//! See [`CompilationFiles`].
+
 use std::collections::HashMap;
 use std::env;
 use std::fmt;
@@ -16,7 +18,9 @@ use crate::util::{self, CargoResult, StableHasher};
 /// This is a generic version number that can be changed to make
 /// backwards-incompatible changes to any file structures in the output
 /// directory. For example, the fingerprint files or the build-script
-/// output files. Normally cargo updates ship with rustc updates which will
+/// output files.
+///
+/// Normally cargo updates ship with rustc updates which will
 /// cause a new hash due to the rustc version changing, but this allows
 /// cargo to be extra careful to deal with different versions of cargo that
 /// use the same rustc version.
@@ -41,7 +45,7 @@ const METADATA_VERSION: u8 = 2;
 ///
 /// This also acts as the main layer of caching provided by Cargo.
 /// For example, we want to cache `cargo build` and `cargo doc` separately, so that running one
-/// does not invalidate the artifacts for the other. We do this by including `CompileMode` in the
+/// does not invalidate the artifacts for the other. We do this by including [`CompileMode`] in the
 /// hash, thus the artifacts go in different folders and do not override each other.
 /// If we don't add something that we should have, for this reason, we get the
 /// correct output but rebuild more than is needed.
@@ -170,7 +174,9 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
 
     /// Gets the metadata for the given unit.
     ///
-    /// See module docs for more details.
+    /// See [`Metadata`] and [`fingerprint`] module for more.
+    ///
+    /// [`fingerprint`]: ../../fingerprint/index.html#fingerprints-and-metadata
     pub fn metadata(&self, unit: &Unit) -> Metadata {
         self.metas[unit].meta_hash
     }
@@ -421,6 +427,9 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
         Some(uplift_path)
     }
 
+    /// Calculates the filenames that the given unit will generate.
+    /// Should use [`CompilationFiles::outputs`] instead
+    /// as it caches the result of this function.
     fn calc_outputs(
         &self,
         unit: &Unit,
@@ -537,6 +546,11 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
     }
 }
 
+/// Gets the metadata hash for the given [`Unit`].
+///
+/// Whne a metadata hash doesn't exist for the given unit,
+/// this calls itself recursively to compute metadata hashes of all its dependencies.
+/// See [`compute_metadata`] for how a single metadata hash is computed.
 fn metadata_of<'a>(
     unit: &Unit,
     cx: &Context<'_, '_>,
@@ -552,6 +566,7 @@ fn metadata_of<'a>(
     &metas[unit]
 }
 
+/// Computes the metadata hash for the given [`Unit`].
 fn compute_metadata(
     unit: &Unit,
     cx: &Context<'_, '_>,
@@ -632,6 +647,7 @@ fn compute_metadata(
     }
 }
 
+/// Hash the version of rustc being used during the build process.
 fn hash_rustc_version(bcx: &BuildContext<'_, '_>, hasher: &mut StableHasher) {
     let vers = &bcx.rustc().version;
     if vers.pre.is_empty() || bcx.config.cli_unstable().separate_nightlies {

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

@@ -1,3 +1,5 @@
+//! [`Context`] is the mutable state used during the build process.
+
 use std::collections::{BTreeSet, HashMap, HashSet};
 use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex};
@@ -27,6 +29,11 @@ use self::compilation_files::CompilationFiles;
 pub use self::compilation_files::{Metadata, OutputFile};
 
 /// Collection of all the stuff that is needed to perform a build.
+///
+/// Different from the [`BuildContext`], `Context` is a _mutable_ state used
+/// throughout the entire build process. Everything is coordinated through this.
+///
+/// [`BuildContext`]: crate::core::compiler::BuildContext
 pub struct Context<'a, 'cfg> {
     /// Mostly static information about the build task.
     pub bcx: &'a BuildContext<'a, 'cfg>,
@@ -126,6 +133,10 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
 
     /// Starts compilation, waits for it to finish, and returns information
     /// about the result of compilation.
+    ///
+    /// See [`ops::cargo_compile`] for a higher-level view of the compile process.
+    ///
+    /// [`ops::cargo_compile`]: ../../../ops/cargo_compile/index.html
     pub fn compile(mut self, exec: &Arc<dyn Executor>) -> CargoResult<Compilation<'cfg>> {
         let mut queue = JobQueue::new(self.bcx);
         let mut plan = BuildPlan::new();
@@ -413,7 +424,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
         self.primary_packages.contains(&unit.pkg.package_id())
     }
 
-    /// Returns the list of filenames read by cargo to generate the `BuildContext`
+    /// Returns the list of filenames read by cargo to generate the [`BuildContext`]
     /// (all `Cargo.toml`, etc.).
     pub fn build_plan_inputs(&self) -> CargoResult<Vec<PathBuf>> {
         // Keep sorted for consistency.
@@ -436,6 +447,8 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
         }
     }
 
+    /// Check if any output file name collision happens.
+    /// See <https://github.com/rust-lang/cargo/issues/6313> for more.
     fn check_collisions(&self) -> CargoResult<()> {
         let mut output_collisions = HashMap::new();
         let describe_collision = |unit: &Unit, other_unit: &Unit, path: &PathBuf| -> String {
@@ -608,6 +621,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
         self.rmeta_required.contains(unit)
     }
 
+    /// Used by `-Zjobserver-per-rustc`.
     pub fn new_jobserver(&mut self) -> CargoResult<Client> {
         let tokens = self.bcx.jobs() as usize;
         let client = Client::new(tokens).with_context(|| "failed to create jobserver")?;