Skip to content

Commit 6c49ea9

Browse files
committed
Auto merge of #11703 - weihanglo:more-doc, r=epage
doc: more doc comments and intra-doc links
2 parents 35e45fd + 25f5267 commit 6c49ea9

File tree

7 files changed

+113
-58
lines changed

7 files changed

+113
-58
lines changed

src/cargo/core/compiler/artifact.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
/// Generate artifact information from unit dependencies for configuring the compiler environment.
1+
//! Generate artifact information from unit dependencies for configuring the compiler environment.
2+
23
use crate::core::compiler::unit_graph::UnitDep;
34
use crate::core::compiler::{Context, CrateType, FileFlavor, Unit};
45
use crate::core::dependency::ArtifactKind;

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

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -348,7 +348,9 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
348348
pub fn prepare(&mut self) -> CargoResult<()> {
349349
let _p = profile::start("preparing layout");
350350

351-
self.files_mut()
351+
self.files
352+
.as_mut()
353+
.unwrap()
352354
.host
353355
.prepare()
354356
.with_context(|| "couldn't prepare build directories")?;
@@ -375,10 +377,6 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
375377
self.files.as_ref().unwrap()
376378
}
377379

378-
fn files_mut(&mut self) -> &mut CompilationFiles<'a, 'cfg> {
379-
self.files.as_mut().unwrap()
380-
}
381-
382380
/// Returns the filenames that the given unit will generate.
383381
pub fn outputs(&self, unit: &Unit) -> CargoResult<Arc<Vec<OutputFile>>> {
384382
self.files.as_ref().unwrap().outputs(unit, self.bcx)

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

Lines changed: 35 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -136,26 +136,47 @@
136136
//!
137137
//! ### dep-info files
138138
//!
139+
//! Cargo has several kinds of "dep info" files:
140+
//!
141+
//! * dep-info files generated by `rustc`.
142+
//! * Fingerprint dep-info files translated from the first one.
143+
//! * dep-info for external build system integration.
144+
//! * Unstable `-Zbinary-dep-depinfo`.
145+
//!
146+
//! #### `rustc` dep-info files
147+
//!
139148
//! Cargo passes the `--emit=dep-info` flag to `rustc` so that `rustc` will
140149
//! generate a "dep info" file (with the `.d` extension). This is a
141150
//! Makefile-like syntax that includes all of the source files used to build
142151
//! the crate. This file is used by Cargo to know which files to check to see
143-
//! if the crate will need to be rebuilt.
144-
//!
145-
//! After `rustc` exits successfully, Cargo will read the dep info file and
146-
//! translate it into a binary format that is stored in the fingerprint
147-
//! directory ([`translate_dep_info`]). The mtime of the fingerprint dep-info
148-
//! file itself is used as the reference for comparing the source files to
149-
//! determine if any of the source files have been modified (see below for
150-
//! more detail). Note that Cargo parses the special `# env-var:...` comments in
151-
//! dep-info files to learn about environment variables that the rustc compile
152-
//! depends on. Cargo then later uses this to trigger a recompile if a
153-
//! referenced env var changes (even if the source didn't change).
152+
//! if the crate will need to be rebuilt. Example:
153+
//!
154+
//! ```makefile
155+
//! /path/to/target/debug/deps/cargo-b6219d178925203d: src/bin/main.rs src/bin/cargo/cli.rs # … etc.
156+
//! ```
157+
//!
158+
//! #### Fingerprint dep-info files
159+
//!
160+
//! After `rustc` exits successfully, Cargo will read the first kind of dep
161+
//! info file and translate it into a binary format that is stored in the
162+
//! fingerprint directory ([`translate_dep_info`]).
163+
//!
164+
//! These are used to quickly scan for any changed files. The mtime of the
165+
//! fingerprint dep-info file itself is used as the reference for comparing the
166+
//! source files to determine if any of the source files have been modified
167+
//! (see [below](#mtime-comparison) for more detail).
168+
//!
169+
//! Note that Cargo parses the special `# env-var:...` comments in dep-info
170+
//! files to learn about environment variables that the rustc compile depends on.
171+
//! Cargo then later uses this to trigger a recompile if a referenced env var
172+
//! changes (even if the source didn't change).
173+
//!
174+
//! #### dep-info files for build system integration.
154175
//!
155176
//! There is also a third dep-info file. Cargo will extend the file created by
156177
//! rustc with some additional information and saves this into the output
157178
//! directory. This is intended for build system integration. See the
158-
//! [`output_depinfo`] module for more detail.
179+
//! [`output_depinfo`] function for more detail.
159180
//!
160181
//! #### -Zbinary-dep-depinfo
161182
//!
@@ -317,8 +338,8 @@
317338
//! [`CompileMode`]: crate::core::compiler::CompileMode
318339
//! [`Lto`]: crate::core::compiler::Lto
319340
//! [`CompileKind`]: crate::core::compiler::CompileKind
320-
//! [`JobQueue`]: ../job_queue/struct.JobQueue.html
321-
//! [`output_depinfo`]: ../output_depinfo/index.html
341+
//! [`JobQueue`]: super::job_queue::JobQueue
342+
//! [`output_depinfo`]: super::output_depinfo()
322343
//! [`CheckDepInfo`]: LocalFingerprint::CheckDepInfo
323344
//! [`RerunIfChanged`]: LocalFingerprint::RerunIfChanged
324345
//! [`CompileMode::RunCustomBuild`]: crate::core::compiler::CompileMode::RunCustomBuild

src/cargo/core/compiler/job.rs

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,33 +5,41 @@ use super::job_queue::JobState;
55
use crate::core::compiler::fingerprint::DirtyReason;
66
use crate::util::CargoResult;
77

8+
/// Represents a unit of [`Work`] with a [`Freshness`] for caller
9+
/// to determine whether to re-execute or not.
810
pub struct Job {
911
work: Work,
1012
fresh: Freshness,
1113
}
1214

15+
/// The basic unit of work.
16+
///
1317
/// Each proc should send its description before starting.
1418
/// It should send either once or close immediately.
1519
pub struct Work {
1620
inner: Box<dyn FnOnce(&JobState<'_, '_>) -> CargoResult<()> + Send>,
1721
}
1822

1923
impl Work {
24+
/// Creates a unit of work.
2025
pub fn new<F>(f: F) -> Work
2126
where
2227
F: FnOnce(&JobState<'_, '_>) -> CargoResult<()> + Send + 'static,
2328
{
2429
Work { inner: Box::new(f) }
2530
}
2631

32+
/// Creates a unit of work that does nothing.
2733
pub fn noop() -> Work {
2834
Work::new(|_| Ok(()))
2935
}
3036

37+
/// Consumes this work by running it.
3138
pub fn call(self, tx: &JobState<'_, '_>) -> CargoResult<()> {
3239
(self.inner)(tx)
3340
}
3441

42+
/// Creates a new unit of work that chains `next` after ourself.
3543
pub fn then(self, next: Work) -> Work {
3644
Work::new(move |state| {
3745
self.call(state)?;
@@ -70,6 +78,7 @@ impl Job {
7078
&self.fresh
7179
}
7280

81+
/// Chains the given work by putting it in front of our own unit of work.
7382
pub fn before(&mut self, next: Work) {
7483
let prev = mem::replace(&mut self.work, Work::noop());
7584
self.work = next.then(prev);

src/cargo/core/compiler/output_depinfo.rs

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,5 @@
1-
//! Module for generating dep-info files.
2-
//!
3-
//! `rustc` generates a dep-info file with a `.d` extension at the same
4-
//! location of the output artifacts as a result of using `--emit=dep-info`.
5-
//! This dep-info file is a Makefile-like syntax that indicates the
6-
//! dependencies needed to build the artifact. Example:
7-
//!
8-
//! ```makefile
9-
//! /path/to/target/debug/deps/cargo-b6219d178925203d: src/bin/main.rs src/bin/cargo/cli.rs # … etc.
10-
//! ```
11-
//!
12-
//! The fingerprint module has code to parse these files, and stores them as
13-
//! binary format in the fingerprint directory. These are used to quickly scan
14-
//! for any changed files.
15-
//!
16-
//! On top of all this, Cargo emits its own dep-info files in the output
17-
//! directory. This is done for every "uplifted" artifact. These are intended
18-
//! to be used with external build systems so that they can detect if Cargo
19-
//! needs to be re-executed. It includes all the entries from the `rustc`
20-
//! dep-info file, and extends it with any `rerun-if-changed` entries from
21-
//! build scripts. It also includes sources from any path dependencies. Registry
22-
//! dependencies are not included under the assumption that changes to them can
23-
//! be detected via changes to `Cargo.lock`.
1+
//! dep-info files for external build system integration.
2+
//! See [`output_depinfo`] for more.
243
254
use cargo_util::paths::normalize_path;
265
use std::collections::{BTreeSet, HashSet};
@@ -32,7 +11,14 @@ use crate::util::{internal, CargoResult};
3211
use cargo_util::paths;
3312
use log::debug;
3413

14+
/// Bacially just normalizes a given path and converts it to a string.
3515
fn render_filename<P: AsRef<Path>>(path: P, basedir: Option<&str>) -> CargoResult<String> {
16+
fn wrap_path(path: &Path) -> CargoResult<String> {
17+
path.to_str()
18+
.ok_or_else(|| internal(format!("path `{:?}` not utf-8", path)))
19+
.map(|f| f.replace(" ", "\\ "))
20+
}
21+
3622
let path = path.as_ref();
3723
if let Some(basedir) = basedir {
3824
let norm_path = normalize_path(path);
@@ -46,12 +32,15 @@ fn render_filename<P: AsRef<Path>>(path: P, basedir: Option<&str>) -> CargoResul
4632
}
4733
}
4834

49-
fn wrap_path(path: &Path) -> CargoResult<String> {
50-
path.to_str()
51-
.ok_or_else(|| internal(format!("path `{:?}` not utf-8", path)))
52-
.map(|f| f.replace(" ", "\\ "))
53-
}
54-
35+
/// Collects all dependencies of the `unit` for the output dep info file.
36+
///
37+
/// Dependencies will be stored in `deps`, including:
38+
///
39+
/// * dependencies from [fingerprint dep-info]
40+
/// * paths from `rerun-if-changed` build script instruction
41+
/// * ...and traverse transitive dependencies recursively
42+
///
43+
/// [fingerprint dep-info]: super::fingerprint#fingerprint-dep-info-files
5544
fn add_deps_for_unit(
5645
deps: &mut BTreeSet<PathBuf>,
5746
cx: &mut Context<'_, '_>,
@@ -105,9 +94,23 @@ fn add_deps_for_unit(
10594
Ok(())
10695
}
10796

108-
/// Save a `.d` dep-info file for the given unit.
97+
/// Save a `.d` dep-info file for the given unit. This is the third kind of
98+
/// dep-info mentioned in [`fingerprint`] module.
99+
///
100+
/// Argument `unit` is expected to be the root unit, which will be uplifted.
101+
///
102+
/// Cargo emits its own dep-info files in the output directory. This is
103+
/// only done for every "uplifted" artifact. These are intended to be used
104+
/// with external build systems so that they can detect if Cargo needs to be
105+
/// re-executed.
106+
///
107+
/// It includes all the entries from the `rustc` dep-info file, and extends it
108+
/// with any `rerun-if-changed` entries from build scripts. It also includes
109+
/// sources from any path dependencies. Registry dependencies are not included
110+
/// under the assumption that changes to them can be detected via changes to
111+
/// `Cargo.lock`.
109112
///
110-
/// This only saves files for uplifted artifacts.
113+
/// [`fingerprint`]: super::fingerprint#dep-info-files
111114
pub fn output_depinfo(cx: &mut Context<'_, '_>, unit: &Unit) -> CargoResult<()> {
112115
let bcx = cx.bcx;
113116
let mut deps = BTreeSet::new();

src/cargo/core/compiler/rustdoc.rs

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,9 @@ use url::Url;
1313

1414
const DOCS_RS_URL: &'static str = "https://docs.rs/";
1515

16-
/// Mode used for `std`.
16+
/// Mode used for `std`. This is for unstable feature [`-Zrustdoc-map`][1].
17+
///
18+
/// [1]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#rustdoc-map
1719
#[derive(Debug, Hash)]
1820
pub enum RustdocExternMode {
1921
/// Use a local `file://` URL.
@@ -54,11 +56,17 @@ impl<'de> serde::de::Deserialize<'de> for RustdocExternMode {
5456
}
5557
}
5658

59+
/// A map of registry names to URLs where documentations are hosted.
60+
/// This is for unstable feature [`-Zrustdoc-map`][1].
61+
///
62+
/// [1]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#rustdoc-map
5763
#[derive(serde::Deserialize, Debug)]
5864
#[serde(default)]
5965
pub struct RustdocExternMap {
6066
#[serde(deserialize_with = "default_crates_io_to_docs_rs")]
61-
pub(crate) registries: HashMap<String, String>,
67+
/// * Key is the registry name in the configuration `[registries.<name>]`.
68+
/// * Value is the URL where the documentation is hosted.
69+
registries: HashMap<String, String>,
6270
std: Option<RustdocExternMode>,
6371
}
6472

@@ -92,6 +100,11 @@ impl hash::Hash for RustdocExternMap {
92100
}
93101
}
94102

103+
/// Adds unstable flag [`--extern-html-root-url`][1] to the given `rustdoc`
104+
/// invocation. This is for unstable feature [`-Zrustdoc-map`][2].
105+
///
106+
/// [1]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#--extern-html-root-url-control-how-rustdoc-links-to-non-local-crates
107+
/// [2]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#rustdoc-map
95108
pub fn add_root_urls(
96109
cx: &Context<'_, '_>,
97110
unit: &Unit,
@@ -191,8 +204,11 @@ pub fn add_root_urls(
191204
Ok(())
192205
}
193206

194-
/// Indicates whether a target should have examples scraped from it
195-
/// by rustdoc. Configured within Cargo.toml.
207+
/// Indicates whether a target should have examples scraped from it by rustdoc.
208+
/// Configured within Cargo.toml and only for unstable feature
209+
/// [`-Zrustdoc-scrape-examples`][1].
210+
///
211+
/// [1]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#scrape-examples
196212
#[derive(Clone, Hash, PartialEq, Eq, PartialOrd, Ord, Debug, Copy)]
197213
pub enum RustdocScrapeExamples {
198214
Enabled,

src/cargo/util/queue.rs

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,12 @@ use std::time::Duration;
77
/// This is a sort of channel where any thread can push to a queue and any
88
/// thread can pop from a queue.
99
///
10-
/// This supports both bounded and unbounded operations. `push` will never block,
11-
/// and allows the queue to grow without bounds. `push_bounded` will block if the
12-
/// queue is over capacity, and will resume once there is enough capacity.
10+
/// This supports both bounded and unbounded operations. [`push`] will never block,
11+
/// and allows the queue to grow without bounds. [`push_bounded`] will block if
12+
/// the queue is over capacity, and will resume once there is enough capacity.
13+
///
14+
/// [`push`]: Self::push
15+
/// [`push_bounded`]: Self::push_bounded
1316
pub struct Queue<T> {
1417
state: Mutex<State<T>>,
1518
popper_cv: Condvar,
@@ -22,6 +25,7 @@ struct State<T> {
2225
}
2326

2427
impl<T> Queue<T> {
28+
/// Creates a queue with a given bound.
2529
pub fn new(bound: usize) -> Queue<T> {
2630
Queue {
2731
state: Mutex::new(State {
@@ -33,6 +37,7 @@ impl<T> Queue<T> {
3337
}
3438
}
3539

40+
/// Pushes an item onto the queue, regardless of the capacity of the queue.
3641
pub fn push(&self, item: T) {
3742
self.state.lock().unwrap().items.push_back(item);
3843
self.popper_cv.notify_one();
@@ -49,6 +54,7 @@ impl<T> Queue<T> {
4954
self.popper_cv.notify_one();
5055
}
5156

57+
/// Pops an item from the queue, blocking if the queue is empty.
5258
pub fn pop(&self, timeout: Duration) -> Option<T> {
5359
let (mut state, result) = self
5460
.popper_cv
@@ -66,6 +72,7 @@ impl<T> Queue<T> {
6672
}
6773
}
6874

75+
/// Pops all items from the queue without blocking.
6976
pub fn try_pop_all(&self) -> Vec<T> {
7077
let mut state = self.state.lock().unwrap();
7178
let result = state.items.drain(..).collect();

0 commit comments

Comments
 (0)