Auto merge of #11841 - epage:contrib, r=weihanglo

docs(contrib): Point compilation docs to doc comments

This is a follow up to #11809, merging the description of compilation with what is in the source code, leaving a breadcrumb for people who were used to going to the old page (for now).  The new entry point for finding this is the doc comment in `lib.rs`

Like with #11809, this also meant increasing the visibility of a mod.  This mod is mostly re-exported already, so this doesn't seem too bad.  I pointed directly to the `job _queue` mod rather than `JobQueue` because the mod had more of an architecture discussion.  For `drain_the_queue`, I also pointed at the mod because it talks about it and this avoided making `DrainState` and `drain_the_queue` `pub(crate)`.

This still leaves
- Files
  - Part of this indexes the architecture based on files generated and should be in `lib.rs`
  - Part of this is filesystem best practices and should be moved out of the architecture overview into some kind of Implementation Practices
- Package and Resolution
- Console Output.  This also likely belongs in an Implementation section
- Likely stuff in the testing section

Author: bors

src/cargo/core/compiler/mod.rs

@@ -42,7 +42,7 @@ mod crate_type;
 mod custom_build;
 pub(crate) mod fingerprint;
 pub mod future_incompat;
-mod job_queue;
+pub(crate) mod job_queue;
 mod layout;
 mod links;
 mod lto;

src/cargo/ops/cargo_compile/mod.rs

@@ -6,27 +6,35 @@
 //! The [`compile`] function will do all the work to compile a workspace. A
 //! rough outline is:
 //!
-//! - Resolve the dependency graph (see [`ops::resolve`]).
-//! - Download any packages needed (see [`PackageSet`](crate::core::PackageSet)).
-//! - Generate a list of top-level "units" of work for the targets the user
+//! 1. Resolve the dependency graph (see [`ops::resolve`]).
+//! 2. Download any packages needed (see [`PackageSet`](crate::core::PackageSet)).
+//! 3. 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_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`]).
-//!     - Create a job queue (see `JobQueue`). The queue checks the
+//! 4. Starting from the root [`Unit`]s, generate the [`UnitGraph`] by walking the dependency graph
+//!   from the resolver.  See also [`unit_dependencies`].
+//! 5. Construct the [`BuildContext`] with all of the information collected so
+//!   far. This is the end of the "front end" of compilation.
+//! 6. Create a [`Context`] which oordinates the compilation process a
+//!   and will perform the following steps:
+//!     1. Prepare the `target` directory (see [`Layout`]).
+//!     2. Create a [`JobQueue`]. The queue checks the
 //!       fingerprint of each `Unit` to determine if it should run or be
 //!       skipped.
-//!     - Execute the queue. Each leaf in the queue's dependency graph is
-//!       executed, and then removed from the graph when finished. This
-//!       repeats until the queue is empty.
+//!     3. Execute the queue via [`drain_the_queue`]. Each leaf in the queue's dependency graph is
+//!        executed, and then removed from the graph when finished. This repeats until the queue is
+//!        empty.  Note that this is the only point in cargo that currently uses threads.
+//! 7. The result of the compilation is stored in the [`Compilation`] struct. This can be used for
+//!    various things, such as running tests after the compilation  has finished.
 //!
 //! **Note**: "target" inside this module generally refers to ["Cargo Target"],
 //! which corresponds to artifact that will be built in a package. Not to be
 //! confused with target-triple or target architecture.
 //!
 //! [`unit_dependencies`]: crate::core::compiler::unit_dependencies
 //! [`Layout`]: crate::core::compiler::Layout
+//! [`JobQueue`]: crate::core::compiler::job_queue
+//! [`drain_the_queue`]: crate::core::compiler::job_queue
 //! ["Cargo Target"]: https://doc.rust-lang.org/nightly/cargo/reference/cargo-targets.html
 
 use std::collections::{HashMap, HashSet};

src/doc/contrib/src/architecture/compilation.md

@@ -1,39 +1,3 @@
 # Compilation
 
-The [`Unit`] is the primary data structure representing a single execution of
-the compiler. It (mostly) contains all the information needed to determine
-which flags to pass to the compiler.
-
-The entry to the compilation process is located in the [`cargo_compile`]
-module. The compilation can be conceptually broken into these steps:
-
-1. Perform dependency resolution (see [the resolution chapter]).
-2. Generate the root `Unit`s, the things the user requested to compile on the
-   command-line. This is done in the [`unit_generator`] module.
-3. Starting from the root `Unit`s, generate the [`UnitGraph`] by walking the
-   dependency graph from the resolver. The `UnitGraph` contains all of the
-   `Unit` structs, and information about the dependency relationships between
-   units. This is done in the [`unit_dependencies`] module.
-4. Construct the [`BuildContext`] with all of the information collected so
-   far. This is the end of the "front end" of compilation.
-5. Create a [`Context`], a large, mutable data structure that coordinates the
-   compilation process.
-6. The [`Context`] will create a [`JobQueue`], a data structure that tracks
-   which units need to be built.
-7. [`drain_the_queue`] does the compilation process. This is the only point in
-   Cargo that currently uses threads.
-8. The result of the compilation is stored in the [`Compilation`] struct. This
-   can be used for various things, such as running tests after the compilation
-   has finished.
-
-[`cargo_compile`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile/mod.rs
-[`unit_generator`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile/unit_generator.rs
-[`UnitGraph`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit_graph.rs
-[the resolution chapter]: packages.md
-[`Unit`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit.rs
-[`unit_dependencies`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit_dependencies.rs
-[`BuildContext`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/build_context/mod.rs
-[`Context`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/context/mod.rs
-[`JobQueue`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/job_queue.rs
-[`drain_the_queue`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/compiler/job_queue.rs#L623-L634
-[`Compilation`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/compilation.rs
+See [nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/ops/cargo_compile/index.html)