doc(build_context): module level doc

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

@@ -1,3 +1,5 @@
+//! [`BuildContext`] is a (mostly) static information about a build task.
+
 use crate::core::compiler::unit_graph::UnitGraph;
 use crate::core::compiler::{BuildConfig, CompileKind, Unit};
 use crate::core::profiles::Profiles;
@@ -15,19 +17,42 @@ pub use self::target_info::{
     FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
 };
 
-/// The build context, containing all information about a build task.
+/// The build context, containing complete infomration needed for a build task
+/// before it gets started.
 ///
 /// It is intended that this is mostly static information. Stuff that mutates
-/// during the build can be found in the parent `Context`. (I say mostly,
+/// during the build can be found in the parent [`Context`]. (I say mostly,
 /// because this has internal caching, but nothing that should be observable
 /// or require &mut.)
+///
+/// As a result, almost every field on `BuildContext` is public, including
+///
+/// * a resolved [`UnitGraph`] of your dependencies,
+/// * a [`Profiles`] containing compiler flags presets,
+/// * a [`RustcTargetData`] containing host and target platform information,
+/// * and a [`PackageSet`] for further package downloads,
+///
+/// just to name a few. Learn more on each own documentation.
+///
+/// # How to use
+///
+/// To prepare a build task, you may not want to use [`BuildContext::new`] directly,
+/// since it is often too lower-level.
+/// Instead, [`ops::create_bcx`] is usually what you are looking for.
+///
+/// [`Context`]: crate::core::compiler::Context
+/// [`ops::create_bcx`]: crate::ops::create_bcx
 pub struct BuildContext<'a, 'cfg> {
     /// The workspace the build is for.
     pub ws: &'a Workspace<'cfg>,
 
     /// The cargo configuration.
     pub config: &'cfg Config,
+
+    /// This contains a collection of compiler flags presets.
     pub profiles: Profiles,
+
+    /// Configuration information for a rustc build.
     pub build_config: &'a BuildConfig,
 
     /// Extra compiler args for either `rustc` or `rustdoc`.
@@ -47,7 +72,7 @@ pub struct BuildContext<'a, 'cfg> {
     /// The dependency graph of units to compile.
     pub unit_graph: UnitGraph,
 
-    /// Reverse-dependencies of documented units, used by the rustdoc --scrape-examples flag.
+    /// Reverse-dependencies of documented units, used by the `rustdoc --scrape-examples` flag.
     pub scrape_units: Vec<Unit>,
 
     /// The list of all kinds that are involved in this build
@@ -88,6 +113,7 @@ impl<'a, 'cfg> BuildContext<'a, 'cfg> {
         })
     }
 
+    /// Information of the `rustc` this build task will use.
     pub fn rustc(&self) -> &Rustc {
         &self.target_data.rustc
     }
@@ -116,14 +142,36 @@ impl<'a, 'cfg> BuildContext<'a, 'cfg> {
         self.build_config.jobs
     }
 
+    /// Extra compiler flags to pass to `rustc` for a given unit.
+    ///
+    /// Although it depends on the caller, in the current Cargo implementation,
+    /// these flags take precendence over those from [`BuildContext::extra_args_for`].
+    ///
+    /// As of now, these flags come from environment variables and configurations.
+    /// See [`TargetInfo.rustflags`] for more on how Cargo collects them.
+    ///
+    /// [`TargetInfo.rustflags`]: TargetInfo::rustflags
     pub fn rustflags_args(&self, unit: &Unit) -> &[String] {
         &self.target_data.info(unit.kind).rustflags
     }
 
+    /// Extra compiler flags to pass to `rustdoc` for a given unit.
+    ///
+    /// Although it depends on the caller, in the current Cargo implementation,
+    /// these flags take precendence over those from [`BuildContext::extra_args_for`].
+    ///
+    /// As of now, these flags come from environment variables and configurations.
+    /// See [`TargetInfo.rustdocflags`] for more on how Cargo collects them.
+    ///
+    /// [`TargetInfo.rustdocflags`]: TargetInfo::rustdocflags
     pub fn rustdocflags_args(&self, unit: &Unit) -> &[String] {
         &self.target_data.info(unit.kind).rustdocflags
     }
 
+    /// Extra compiler args for either `rustc` or `rustdoc`.
+    ///
+    /// As of now, these flags come from the trailing args of either
+    /// `cargo rustc` or `cargo rustdoc`.
     pub fn extra_args_for(&self, unit: &Unit) -> Option<&Vec<String>> {
         self.extra_compiler_args.get(unit)
     }