doc: enhancements of mods under compiler

Author: weihanglo

src/cargo/core/compiler/compilation.rs

@@ -1,3 +1,5 @@
+//! Type definitions for the result of a compilation.
+
 use std::collections::{BTreeSet, HashMap};
 use std::env;
 use std::ffi::{OsStr, OsString};

src/cargo/core/compiler/compile_kind.rs

@@ -1,3 +1,5 @@
+//! Type definitions for cross-compilation.
+
 use crate::core::Target;
 use crate::util::errors::CargoResult;
 use crate::util::interning::InternedString;

src/cargo/core/compiler/timings.rs

@@ -16,6 +16,13 @@ use std::io::{BufWriter, Write};
 use std::thread::available_parallelism;
 use std::time::{Duration, Instant, SystemTime};
 
+/// Tracking information for the entire build.
+///
+/// Methods on this structure are generally called from the main thread of a
+/// running [`JobQueue`] instance (`DrainState` in specific) when the queue
+/// receives messages from spawned off threads.
+///
+/// [`JobQueue`]: super::JobQueue
 pub struct Timings<'cfg> {
     config: &'cfg Config,
     /// Whether or not timings should be captured.
@@ -253,12 +260,12 @@ impl<'cfg> Timings<'cfg> {
         self.concurrency.push(c);
     }
 
-    /// Mark that a fresh unit was encountered.
+    /// Mark that a fresh unit was encountered. (No re-compile needed)
     pub fn add_fresh(&mut self) {
         self.total_fresh += 1;
     }
 
-    /// Mark that a dirty unit was encountered.
+    /// Mark that a dirty unit was encountered. (Re-compile needed)
     pub fn add_dirty(&mut self) {
         self.total_dirty += 1;
     }
@@ -456,6 +463,8 @@ impl<'cfg> Timings<'cfg> {
         Ok(())
     }
 
+    /// Write timing data in JavaScript. Primarily for `timings.js` to put data
+    /// in a `<script>` HTML element to draw graphs.
     fn write_js_data(&self, f: &mut impl Write) -> CargoResult<()> {
         // Create a map to link indices of unlocked units.
         let unit_map: HashMap<Unit, usize> = self

src/cargo/core/compiler/unit.rs

@@ -1,3 +1,5 @@
+//! Types and impls for [`Unit`].
+
 use crate::core::compiler::unit_dependencies::IsArtifact;
 use crate::core::compiler::{CompileKind, CompileMode, CompileTarget, CrateType};
 use crate::core::manifest::{Target, TargetKind};
@@ -108,6 +110,9 @@ impl UnitInner {
 }
 
 impl Unit {
+    /// Gets the unique key for [`-Zbuild-plan`].
+    ///
+    /// [`-Zbuild-plan`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-plan
     pub fn buildkey(&self) -> String {
         format!("{}-{}", self.pkg.name(), short_hash(self))
     }

src/cargo/core/compiler/unit_graph.rs

@@ -1,3 +1,7 @@
+//! Serialization of [`UnitGraph`] for unstable option [`--unit-graph`].
+//!
+//! [`--unit-graph`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#unit-graph
+
 use crate::core::compiler::Unit;
 use crate::core::compiler::{CompileKind, CompileMode};
 use crate::core::profiles::{Profile, UnitFor};
@@ -69,6 +73,8 @@ struct SerializedUnitDep {
     // internal detail that is mostly used for building the graph.
 }
 
+/// Outputs a JSON serialization of [`UnitGraph`] for given `root_units`
+/// to the standard output.
 pub fn emit_serialized_unit_graph(
     root_units: &[Unit],
     unit_graph: &UnitGraph,