Auto merge of #11458 - weihanglo:doc/unit-generator, r=epage

Rename `generate_units` -> `generate_root_units`

src/cargo/ops/cargo_compile/compile_filter.rs

@@ -28,11 +28,11 @@ pub enum FilterRule {
 /// Filter to apply to the root package to select which Cargo targets will be built.
 /// (examples, bins, benches, tests, ...)
 ///
-/// The actual filter process happens inside [`generate_units`].
+/// The actual filter process happens inside [`generate_root_units`].
 ///
 /// Not to be confused with [`Packages`], which opts in packages to be built.
 ///
-/// [`generate_units`]: super::UnitGenerator::generate_units
+/// [`generate_root_units`]: super::UnitGenerator::generate_root_units
 /// [`Packages`]: crate::ops::Packages
 #[derive(Debug)]
 pub enum CompileFilter {
@@ -175,8 +175,11 @@ impl CompileFilter {
     /// all targets with `tested` flag on, whereas [`CompileFilter::Default`]
     /// may include additional example targets to ensure they can be compiled.
     ///
-    /// Note that the actual behavior is subject to `filter_default_targets`
-    /// and `generate_units` though.
+    /// Note that the actual behavior is subject to [`filter_default_targets`]
+    /// and [`generate_root_units`] though.
+    ///
+    /// [`generate_root_units`]: super::UnitGenerator::generate_root_units
+    /// [`filter_default_targets`]: super::UnitGenerator::filter_default_targets
     pub fn all_test_targets() -> Self {
         Self::Only {
             all_targets: false,
@@ -234,7 +237,10 @@ impl CompileFilter {
     }
 
     /// Selects targets for "cargo run". for logic to select targets for other
-    /// subcommands, see `generate_units` and `filter_default_targets`.
+    /// subcommands, see [`generate_root_units`] and [`filter_default_targets`].
+    ///
+    /// [`generate_root_units`]: super::UnitGenerator::generate_root_units
+    /// [`filter_default_targets`]: super::UnitGenerator::filter_default_targets
     pub fn target_run(&self, target: &Target) -> bool {
         match *self {
             CompileFilter::Default { .. } => true,

src/cargo/ops/cargo_compile/mod.rs

@@ -10,7 +10,7 @@
 //! - Download any packages needed (see [`PackageSet`](crate::core::PackageSet)).
 //! - Generate a list of top-level "units" of work for the targets the user
 //!   requested on the command-line. Each [`Unit`] corresponds to a compiler
-//!   invocation. This is done in this module ([`UnitGenerator::generate_units`]).
+//!   invocation. This is done in this module ([`UnitGenerator::generate_root_units`]).
 //! - Build the graph of `Unit` dependencies (see [`unit_dependencies`]).
 //! - Create a [`Context`] which will perform the following steps:
 //!     - Prepare the `target` directory (see [`Layout`]).
@@ -344,7 +344,7 @@ pub fn create_bcx<'a, 'cfg>(
         .collect();
 
     // Passing `build_config.requested_kinds` instead of
-    // `explicit_host_kinds` here so that `generate_units` can do
+    // `explicit_host_kinds` here so that `generate_root_units` can do
     // its own special handling of `CompileKind::Host`. It will
     // internally replace the host kind by the `explicit_host_kind`
     // before setting as a unit.
@@ -363,7 +363,7 @@ pub fn create_bcx<'a, 'cfg>(
         interner,
         has_dev_units,
     };
-    let mut units = generator.generate_units()?;
+    let mut units = generator.generate_root_units()?;
 
     if let Some(args) = target_rustc_crate_types {
         override_rustc_crate_types(&mut units, args, interner)?;
@@ -375,7 +375,7 @@ pub fn create_bcx<'a, 'cfg>(
             mode: CompileMode::Docscrape,
             ..generator
         };
-        let all_units = scrape_generator.generate_units()?;
+        let all_units = scrape_generator.generate_root_units()?;
 
         let valid_units = all_units
             .into_iter()

src/cargo/ops/cargo_compile/unit_generator.rs

@@ -33,7 +33,16 @@ struct Proposal<'a> {
     mode: CompileMode,
 }
 
-/// The context needed for generating units.
+/// The context needed for generating root units,
+/// which are pacakges the user has requested to compile.
+///
+/// To generate a full [`UnitGraph`],
+/// generally you need to call [`generate_root_units`] first,
+/// and then provide the output to [`build_unit_dependencies`].
+///
+/// [`generate_root_units`]: UnitGenerator::generate_root_units
+/// [`build_unit_dependencies`]: crate::core::compiler::unit_dependencies::build_unit_dependencies
+/// [`UnitGraph`]: crate::core::compiler::unit_graph::UnitGraph
 pub(super) struct UnitGenerator<'a, 'cfg> {
     pub ws: &'a Workspace<'cfg>,
     pub packages: &'a [&'a Package],
@@ -303,7 +312,7 @@ impl<'a> UnitGenerator<'a, '_> {
         Ok(proposals)
     }
 
-    /// Create a list of proposed targets given the context in `TargetGenerator`
+    /// Create a list of proposed targets given the context in `UnitGenerator`
     fn create_proposals(&self) -> CargoResult<Vec<Proposal<'_>>> {
         let mut proposals: Vec<Proposal<'_>> = Vec::new();
 
@@ -658,8 +667,10 @@ impl<'a> UnitGenerator<'a, '_> {
     }
 
     /// Generates all the base units for the packages the user has requested to
-    /// compile. Dependencies for these units are computed later in `unit_dependencies`.
-    pub fn generate_units(&self) -> CargoResult<Vec<Unit>> {
+    /// compile. Dependencies for these units are computed later in [`unit_dependencies`].
+    ///
+    /// [`unit_dependencies`]: crate::core::compiler::unit_dependencies
+    pub fn generate_root_units(&self) -> CargoResult<Vec<Unit>> {
         let proposals = self.create_proposals()?;
         self.proposals_to_units(proposals)
     }

src/doc/contrib/src/tests/writing.md

@@ -269,7 +269,7 @@ environment. The general process is:
    * `/path/to/my/cargo/target/debug/cargo check`
    * Using a debugger like `lldb` or `gdb`:
         1. `lldb /path/to/my/cargo/target/debug/cargo`
-        2. Set a breakpoint, for example: `b generate_units`
+        2. Set a breakpoint, for example: `b generate_root_units`
         3. Run with arguments: `r check`
 
 [`testsuite`]: https://github.com/rust-lang/cargo/tree/master/tests/testsuite/