rustdoc/passes/
mod.rs

1//! Contains information about "passes", used to modify crate information during the documentation
2//! process.
3
4use self::Condition::*;
5use crate::clean;
6use crate::core::DocContext;
7
8mod stripper;
9pub(crate) use stripper::*;
10
11mod strip_aliased_non_local;
12pub(crate) use self::strip_aliased_non_local::STRIP_ALIASED_NON_LOCAL;
13
14mod strip_hidden;
15pub(crate) use self::strip_hidden::STRIP_HIDDEN;
16
17mod strip_private;
18pub(crate) use self::strip_private::STRIP_PRIVATE;
19
20mod strip_priv_imports;
21pub(crate) use self::strip_priv_imports::STRIP_PRIV_IMPORTS;
22
23mod propagate_doc_cfg;
24pub(crate) use self::propagate_doc_cfg::PROPAGATE_DOC_CFG;
25
26mod propagate_stability;
27pub(crate) use self::propagate_stability::PROPAGATE_STABILITY;
28
29pub(crate) mod collect_intra_doc_links;
30pub(crate) use self::collect_intra_doc_links::COLLECT_INTRA_DOC_LINKS;
31
32mod check_doc_test_visibility;
33pub(crate) use self::check_doc_test_visibility::CHECK_DOC_TEST_VISIBILITY;
34
35mod check_doc_cfg;
36pub(crate) use self::check_doc_cfg::CHECK_DOC_CFG;
37
38mod collect_trait_impls;
39pub(crate) use self::collect_trait_impls::COLLECT_TRAIT_IMPLS;
40
41mod calculate_doc_coverage;
42pub(crate) use self::calculate_doc_coverage::CALCULATE_DOC_COVERAGE;
43
44mod lint;
45pub(crate) use self::lint::RUN_LINTS;
46
47/// A single pass over the cleaned documentation.
48///
49/// Runs in the compiler context, so it has access to types and traits and the like.
50#[derive(Copy, Clone)]
51pub(crate) struct Pass {
52    pub(crate) name: &'static str,
53    pub(crate) run: Option<fn(clean::Crate, &mut DocContext<'_>) -> clean::Crate>,
54    pub(crate) description: &'static str,
55}
56
57/// In a list of passes, a pass that may or may not need to be run depending on options.
58#[derive(Copy, Clone)]
59pub(crate) struct ConditionalPass {
60    pub(crate) pass: Pass,
61    pub(crate) condition: Condition,
62}
63
64/// How to decide whether to run a conditional pass.
65#[derive(Copy, Clone)]
66pub(crate) enum Condition {
67    Always,
68    /// When `--document-private-items` is passed.
69    WhenDocumentPrivate,
70    /// When `--document-private-items` is not passed.
71    WhenNotDocumentPrivate,
72    /// When `--document-hidden-items` is not passed.
73    WhenNotDocumentHidden,
74}
75
76/// The full list of passes.
77pub(crate) const PASSES: &[Pass] = &[
78    CHECK_DOC_CFG,
79    CHECK_DOC_TEST_VISIBILITY,
80    STRIP_ALIASED_NON_LOCAL,
81    STRIP_HIDDEN,
82    STRIP_PRIVATE,
83    STRIP_PRIV_IMPORTS,
84    PROPAGATE_DOC_CFG,
85    PROPAGATE_STABILITY,
86    COLLECT_INTRA_DOC_LINKS,
87    COLLECT_TRAIT_IMPLS,
88    CALCULATE_DOC_COVERAGE,
89    RUN_LINTS,
90];
91
92/// The list of passes run by default.
93pub(crate) const DEFAULT_PASSES: &[ConditionalPass] = &[
94    ConditionalPass::always(COLLECT_TRAIT_IMPLS),
95    ConditionalPass::always(CHECK_DOC_TEST_VISIBILITY),
96    ConditionalPass::always(CHECK_DOC_CFG),
97    ConditionalPass::always(STRIP_ALIASED_NON_LOCAL),
98    ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden),
99    ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate),
100    ConditionalPass::new(STRIP_PRIV_IMPORTS, WhenDocumentPrivate),
101    ConditionalPass::always(COLLECT_INTRA_DOC_LINKS),
102    ConditionalPass::always(PROPAGATE_DOC_CFG),
103    ConditionalPass::always(PROPAGATE_STABILITY),
104    ConditionalPass::always(RUN_LINTS),
105];
106
107/// The list of default passes run when `--doc-coverage` is passed to rustdoc.
108pub(crate) const COVERAGE_PASSES: &[ConditionalPass] = &[
109    ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden),
110    ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate),
111    ConditionalPass::always(CALCULATE_DOC_COVERAGE),
112];
113
114impl ConditionalPass {
115    pub(crate) const fn always(pass: Pass) -> Self {
116        Self::new(pass, Always)
117    }
118
119    pub(crate) const fn new(pass: Pass, condition: Condition) -> Self {
120        ConditionalPass { pass, condition }
121    }
122}
123
124/// Returns the given default set of passes.
125pub(crate) fn defaults(show_coverage: bool) -> &'static [ConditionalPass] {
126    if show_coverage { COVERAGE_PASSES } else { DEFAULT_PASSES }
127}
rustdoc/passes/mod.rs

rustdoc/passes/
mod.rs
