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::{
34    CHECK_DOC_TEST_VISIBILITY, Tests, should_have_doc_example,
35};
36
37mod collect_trait_impls;
38pub(crate) use self::collect_trait_impls::COLLECT_TRAIT_IMPLS;
39
40mod lint;
41pub(crate) use self::lint::RUN_LINTS;
42
43/// A single pass over the cleaned documentation.
44///
45/// Runs in the compiler context, so it has access to types and traits and the like.
46#[derive(Copy, Clone)]
47pub(crate) struct Pass {
48    pub(crate) name: &'static str,
49    pub(crate) run: Option<fn(clean::Crate, &mut DocContext<'_>) -> clean::Crate>,
50    pub(crate) description: &'static str,
51}
52
53/// In a list of passes, a pass that may or may not need to be run depending on options.
54#[derive(Copy, Clone)]
55pub(crate) struct ConditionalPass {
56    pub(crate) pass: Pass,
57    pub(crate) condition: Condition,
58}
59
60/// How to decide whether to run a conditional pass.
61#[derive(Copy, Clone)]
62pub(crate) enum Condition {
63    Always,
64    /// When `--document-private-items` is passed.
65    WhenDocumentPrivate,
66    /// When `--document-private-items` is not passed.
67    WhenNotDocumentPrivate,
68    /// When `--document-hidden-items` is not passed.
69    WhenNotDocumentHidden,
70}
71
72/// The full list of passes.
73pub(crate) const PASSES: &[Pass] = &[
74    CHECK_DOC_TEST_VISIBILITY,
75    PROPAGATE_DOC_CFG,
76    STRIP_ALIASED_NON_LOCAL,
77    STRIP_HIDDEN,
78    STRIP_PRIVATE,
79    STRIP_PRIV_IMPORTS,
80    PROPAGATE_STABILITY,
81    COLLECT_INTRA_DOC_LINKS,
82    COLLECT_TRAIT_IMPLS,
83    RUN_LINTS,
84];
85
86/// The list of passes run by default.
87pub(crate) const DEFAULT_PASSES: &[ConditionalPass] = &[
88    ConditionalPass::always(COLLECT_TRAIT_IMPLS),
89    ConditionalPass::always(CHECK_DOC_TEST_VISIBILITY),
90    ConditionalPass::always(STRIP_ALIASED_NON_LOCAL),
91    ConditionalPass::always(PROPAGATE_DOC_CFG),
92    ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden),
93    ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate),
94    ConditionalPass::new(STRIP_PRIV_IMPORTS, WhenDocumentPrivate),
95    ConditionalPass::always(COLLECT_INTRA_DOC_LINKS),
96    ConditionalPass::always(PROPAGATE_STABILITY),
97    ConditionalPass::always(RUN_LINTS),
98];
99
100/// The list of default passes run when `--doc-coverage` is passed to rustdoc.
101pub(crate) const COVERAGE_PASSES: &[ConditionalPass] = &[
102    ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden),
103    ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate),
104];
105
106impl ConditionalPass {
107    pub(crate) const fn always(pass: Pass) -> Self {
108        Self::new(pass, Always)
109    }
110
111    pub(crate) const fn new(pass: Pass, condition: Condition) -> Self {
112        ConditionalPass { pass, condition }
113    }
114}
115
116/// Returns the given default set of passes.
117pub(crate) fn defaults(show_coverage: bool) -> &'static [ConditionalPass] {
118    if show_coverage { COVERAGE_PASSES } else { DEFAULT_PASSES }
119}
rustdoc/passes/mod.rs

rustdoc/passes/
mod.rs
