1 //! Contains information about "passes", used to modify crate information during the documentation
2 //! process.
3
4 use rustc_middle::ty::TyCtxt;
5 use rustc_resolve::rustdoc::DocFragmentKind;
6 use rustc_span::{InnerSpan, Span, DUMMY_SP};
7 use std::ops::Range;
8
9 use self::Condition::*;
10 use crate::clean;
11 use crate::core::DocContext;
12
13 mod stripper;
14 pub(crate) use stripper::*;
15
16 mod strip_hidden;
17 pub(crate) use self::strip_hidden::STRIP_HIDDEN;
18
19 mod strip_private;
20 pub(crate) use self::strip_private::STRIP_PRIVATE;
21
22 mod strip_priv_imports;
23 pub(crate) use self::strip_priv_imports::STRIP_PRIV_IMPORTS;
24
25 mod propagate_doc_cfg;
26 pub(crate) use self::propagate_doc_cfg::PROPAGATE_DOC_CFG;
27
28 pub(crate) mod collect_intra_doc_links;
29 pub(crate) use self::collect_intra_doc_links::COLLECT_INTRA_DOC_LINKS;
30
31 mod check_doc_test_visibility;
32 pub(crate) use self::check_doc_test_visibility::CHECK_DOC_TEST_VISIBILITY;
33
34 mod collect_trait_impls;
35 pub(crate) use self::collect_trait_impls::COLLECT_TRAIT_IMPLS;
36
37 mod calculate_doc_coverage;
38 pub(crate) use self::calculate_doc_coverage::CALCULATE_DOC_COVERAGE;
39
40 mod lint;
41 pub(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)]
47 pub(crate) struct Pass {
48 pub(crate) name: &'static str,
49 pub(crate) run: 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)]
55 pub(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)]
62 pub(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.
73 pub(crate) const PASSES: &[Pass] = &[
74 CHECK_DOC_TEST_VISIBILITY,
75 STRIP_HIDDEN,
76 STRIP_PRIVATE,
77 STRIP_PRIV_IMPORTS,
78 PROPAGATE_DOC_CFG,
79 COLLECT_INTRA_DOC_LINKS,
80 COLLECT_TRAIT_IMPLS,
81 CALCULATE_DOC_COVERAGE,
82 RUN_LINTS,
83 ];
84
85 /// The list of passes run by default.
86 pub(crate) const DEFAULT_PASSES: &[ConditionalPass] = &[
87 ConditionalPass::always(COLLECT_TRAIT_IMPLS),
88 ConditionalPass::always(CHECK_DOC_TEST_VISIBILITY),
89 ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden),
90 ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate),
91 ConditionalPass::new(STRIP_PRIV_IMPORTS, WhenDocumentPrivate),
92 ConditionalPass::always(COLLECT_INTRA_DOC_LINKS),
93 ConditionalPass::always(PROPAGATE_DOC_CFG),
94 ConditionalPass::always(RUN_LINTS),
95 ];
96
97 /// The list of default passes run when `--doc-coverage` is passed to rustdoc.
98 pub(crate) const COVERAGE_PASSES: &[ConditionalPass] = &[
99 ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden),
100 ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate),
101 ConditionalPass::always(CALCULATE_DOC_COVERAGE),
102 ];
103
104 impl ConditionalPass {
always(pass: Pass) -> Self105 pub(crate) const fn always(pass: Pass) -> Self {
106 Self::new(pass, Always)
107 }
108
new(pass: Pass, condition: Condition) -> Self109 pub(crate) const fn new(pass: Pass, condition: Condition) -> Self {
110 ConditionalPass { pass, condition }
111 }
112 }
113
114 /// Returns the given default set of passes.
defaults(show_coverage: bool) -> &'static [ConditionalPass]115 pub(crate) fn defaults(show_coverage: bool) -> &'static [ConditionalPass] {
116 if show_coverage { COVERAGE_PASSES } else { DEFAULT_PASSES }
117 }
118
119 /// Returns a span encompassing all the given attributes.
span_of_attrs(attrs: &clean::Attributes) -> Option<Span>120 pub(crate) fn span_of_attrs(attrs: &clean::Attributes) -> Option<Span> {
121 if attrs.doc_strings.is_empty() {
122 return None;
123 }
124 let start = attrs.doc_strings[0].span;
125 if start == DUMMY_SP {
126 return None;
127 }
128 let end = attrs.doc_strings.last().expect("no doc strings provided").span;
129 Some(start.to(end))
130 }
131
132 /// Attempts to match a range of bytes from parsed markdown to a `Span` in the source code.
133 ///
134 /// This method will return `None` if we cannot construct a span from the source map or if the
135 /// attributes are not all sugared doc comments. It's difficult to calculate the correct span in
136 /// that case due to escaping and other source features.
source_span_for_markdown_range( tcx: TyCtxt<'_>, markdown: &str, md_range: &Range<usize>, attrs: &clean::Attributes, ) -> Option<Span>137 pub(crate) fn source_span_for_markdown_range(
138 tcx: TyCtxt<'_>,
139 markdown: &str,
140 md_range: &Range<usize>,
141 attrs: &clean::Attributes,
142 ) -> Option<Span> {
143 let is_all_sugared_doc =
144 attrs.doc_strings.iter().all(|frag| frag.kind == DocFragmentKind::SugaredDoc);
145
146 if !is_all_sugared_doc {
147 return None;
148 }
149
150 let snippet = tcx.sess.source_map().span_to_snippet(span_of_attrs(attrs)?).ok()?;
151
152 let starting_line = markdown[..md_range.start].matches('\n').count();
153 let ending_line = starting_line + markdown[md_range.start..md_range.end].matches('\n').count();
154
155 // We use `split_terminator('\n')` instead of `lines()` when counting bytes so that we treat
156 // CRLF and LF line endings the same way.
157 let mut src_lines = snippet.split_terminator('\n');
158 let md_lines = markdown.split_terminator('\n');
159
160 // The number of bytes from the source span to the markdown span that are not part
161 // of the markdown, like comment markers.
162 let mut start_bytes = 0;
163 let mut end_bytes = 0;
164
165 'outer: for (line_no, md_line) in md_lines.enumerate() {
166 loop {
167 let source_line = src_lines.next()?;
168 match source_line.find(md_line) {
169 Some(offset) => {
170 if line_no == starting_line {
171 start_bytes += offset;
172
173 if starting_line == ending_line {
174 break 'outer;
175 }
176 } else if line_no == ending_line {
177 end_bytes += offset;
178 break 'outer;
179 } else if line_no < starting_line {
180 start_bytes += source_line.len() - md_line.len();
181 } else {
182 end_bytes += source_line.len() - md_line.len();
183 }
184 break;
185 }
186 None => {
187 // Since this is a source line that doesn't include a markdown line,
188 // we have to count the newline that we split from earlier.
189 if line_no <= starting_line {
190 start_bytes += source_line.len() + 1;
191 } else {
192 end_bytes += source_line.len() + 1;
193 }
194 }
195 }
196 }
197 }
198
199 Some(span_of_attrs(attrs)?.from_inner(InnerSpan::new(
200 md_range.start + start_bytes,
201 md_range.end + start_bytes + end_bytes,
202 )))
203 }
204