Auto merge of #7625 - ehuss:some-comments, r=Eh2406

Some random comments and docstrings.

Just some things I came across that I felt could use some more information.

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

@@ -50,6 +50,8 @@ impl fmt::Display for Metadata {
     }
 }
 
+/// Collection of information about the files emitted by the compiler, and the
+/// output directory structure.
 pub struct CompilationFiles<'a, 'cfg> {
     /// The target directory layout for the host (and target if it is the same as host).
     pub(super) host: Layout,
@@ -66,6 +68,7 @@ pub struct CompilationFiles<'a, 'cfg> {
     outputs: HashMap<Unit<'a>, LazyCell<Arc<Vec<OutputFile>>>>,
 }
 
+/// Info about a single file emitted by the compiler.
 #[derive(Debug)]
 pub struct OutputFile {
     /// Absolute path to the file that will be produced by the build process.
@@ -227,6 +230,7 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
         }
     }
 
+    /// Returns the filenames that the given unit will generate.
     pub(super) fn outputs(
         &self,
         unit: &Unit<'a>,

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

@@ -163,7 +163,9 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
             plan.output_plan();
         }
 
+        // Collect the result of the build into `self.compilation`.
         for unit in units.iter() {
+            // Collect tests and executables.
             for output in self.outputs(unit)?.iter() {
                 if output.flavor == FileFlavor::DebugInfo || output.flavor == FileFlavor::Auxiliary
                 {
@@ -183,6 +185,8 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
                 }
             }
 
+            // If the unit has a build script, add `OUT_DIR` to the
+            // environment variables.
             for dep in self.dep_targets(unit).iter() {
                 if !unit.target.is_lib() {
                     continue;
@@ -198,6 +202,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
                 }
             }
 
+            // Collect information for `rustdoc --test`.
             if unit.mode.is_doc_test() {
                 // Note that we can *only* doc-test rlib outputs here. A
                 // staticlib output cannot be linked by the compiler (it just
@@ -231,6 +236,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
                 });
             }
 
+            // Collect the enabled features.
             let feats = &unit.features;
             if !feats.is_empty() {
                 self.compilation
@@ -243,6 +249,8 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
                             .collect()
                     });
             }
+
+            // Collect rustdocflags.
             let rustdocflags = self.bcx.rustdocflags_args(unit);
             if !rustdocflags.is_empty() {
                 self.compilation

src/cargo/core/compiler/fingerprint.rs

@@ -313,7 +313,7 @@ pub fn prepare_target<'a, 'cfg>(
 }
 
 /// Dependency edge information for fingerprints. This is generated for each
-/// unit in `dep_targets` and is stored in a `Fingerprint` below.
+/// dependency and is stored in a `Fingerprint` below.
 #[derive(Clone)]
 struct DepFingerprint {
     /// The hash of the package id that this dependency points to
@@ -1626,6 +1626,10 @@ pub fn translate_dep_info(
     Ok(())
 }
 
+/// Parse the `.d` dep-info file generated by rustc.
+///
+/// Result is a Vec of `(target, prerequisites)` tuples where `target` is the
+/// rule name, and `prerequisites` is a list of files that it depends on.
 pub fn parse_rustc_dep_info(rustc_dep_info: &Path) -> CargoResult<Vec<(String, Vec<String>)>> {
     let contents = paths::read(rustc_dep_info)?;
     contents

src/cargo/core/compiler/output_depinfo.rs

@@ -1,3 +1,27 @@
+//! Module for generating dep-info files.
+//!
+//! `rustc` generates a dep-info file with a `.d` extension at the same
+//! location of the output artifacts as a result of using `--emit=dep-info`.
+//! This dep-info file is a Makefile-like syntax that indicates the
+//! dependencies needed to build the artifact. Example:
+//!
+//! ```makefile
+//! /path/to/target/debug/deps/cargo-b6219d178925203d: src/bin/main.rs src/bin/cargo/cli.rs # … etc.
+//! ```
+//!
+//! The fingerprint module has code to parse these files, and stores them as
+//! binary format in the fingerprint directory. These are used to quickly scan
+//! for any changed files.
+//!
+//! On top of all this, Cargo emits its own dep-info files in the output
+//! directory. This is done for every "uplifted" artifact. These are intended
+//! to be used with external build systems so that they can detect if Cargo
+//! needs to be re-executed. It includes all the entries from the `rustc`
+//! dep-info file, and extends it with any `rerun-if-changed` entries from
+//! build scripts. It also includes sources from any path dependencies. Registry
+//! dependencies are not included under the assumption that changes to them can
+//! be detected via changes to `Cargo.lock`.
+
 use std::collections::{BTreeSet, HashSet};
 use std::fs::File;
 use std::io::{BufWriter, Write};
@@ -75,6 +99,9 @@ fn add_deps_for_unit<'a, 'b>(
     Ok(())
 }
 
+/// Save a `.d` dep-info file for the given unit.
+///
+/// This only saves files for uplifted artifacts.
 pub fn output_depinfo<'a, 'b>(cx: &mut Context<'a, 'b>, unit: &Unit<'a>) -> CargoResult<()> {
     let bcx = cx.bcx;
     let mut deps = BTreeSet::new();