src/librustdoc/passes/mod.rs

   1 //! Contains information about "passes", used to modify crate information during the documentation
   2 //! process.
   3
   4 use rustc_span::{InnerSpan, Span, DUMMY_SP};
   5 use std::ops::Range;
   6
   7 use self::Condition::*;
   8 use crate::clean::{self, DocFragmentKind};
   9 use crate::core::DocContext;
  10
  11 mod stripper;
  12 pub use stripper::*;
  13
  14 mod collapse_docs;
  15 pub use self::collapse_docs::COLLAPSE_DOCS;
  16
  17 mod strip_hidden;
  18 pub use self::strip_hidden::STRIP_HIDDEN;
  19
  20 mod strip_private;
  21 pub use self::strip_private::STRIP_PRIVATE;
  22
  23 mod strip_priv_imports;
  24 pub use self::strip_priv_imports::STRIP_PRIV_IMPORTS;
  25
  26 mod unindent_comments;
  27 pub use self::unindent_comments::UNINDENT_COMMENTS;
  28
  29 mod propagate_doc_cfg;
  30 pub use self::propagate_doc_cfg::PROPAGATE_DOC_CFG;
  31
  32 mod collect_intra_doc_links;
  33 pub use self::collect_intra_doc_links::COLLECT_INTRA_DOC_LINKS;
  34
  35 mod doc_test_lints;
  36 pub use self::doc_test_lints::CHECK_PRIVATE_ITEMS_DOC_TESTS;
  37
  38 mod collect_trait_impls;
  39 pub use self::collect_trait_impls::COLLECT_TRAIT_IMPLS;
  40
  41 mod check_code_block_syntax;
  42 pub use self::check_code_block_syntax::CHECK_CODE_BLOCK_SYNTAX;
  43
  44 mod calculate_doc_coverage;
  45 pub use self::calculate_doc_coverage::CALCULATE_DOC_COVERAGE;
  46
  47 mod html_tags;
  48 pub use self::html_tags::CHECK_INVALID_HTML_TAGS;
  49
  50 /// A single pass over the cleaned documentation.
  51 ///
  52 /// Runs in the compiler context, so it has access to types and traits and the like.
  53 #[derive(Copy, Clone)]
  54 pub struct Pass {
  55     pub name: &'static str,
  56     pub run: fn(clean::Crate, &DocContext<'_>) -> clean::Crate,
  57     pub description: &'static str,
  58 }
  59
  60 /// In a list of passes, a pass that may or may not need to be run depending on options.
  61 #[derive(Copy, Clone)]
  62 pub struct ConditionalPass {
  63     pub pass: Pass,
  64     pub condition: Condition,
  65 }
  66
  67 /// How to decide whether to run a conditional pass.
  68 #[derive(Copy, Clone)]
  69 pub enum Condition {
  70     Always,
  71     /// When `--document-private-items` is passed.
  72     WhenDocumentPrivate,
  73     /// When `--document-private-items` is not passed.
  74     WhenNotDocumentPrivate,
  75     /// When `--document-hidden-items` is not passed.
  76     WhenNotDocumentHidden,
  77 }
  78
  79 /// The full list of passes.
  80 pub const PASSES: &[Pass] = &[
  81     CHECK_PRIVATE_ITEMS_DOC_TESTS,
  82     STRIP_HIDDEN,
  83     UNINDENT_COMMENTS,
  84     COLLAPSE_DOCS,
  85     STRIP_PRIVATE,
  86     STRIP_PRIV_IMPORTS,
  87     PROPAGATE_DOC_CFG,
  88     COLLECT_INTRA_DOC_LINKS,
  89     CHECK_CODE_BLOCK_SYNTAX,
  90     COLLECT_TRAIT_IMPLS,
  91     CALCULATE_DOC_COVERAGE,
  92     CHECK_INVALID_HTML_TAGS,
  93 ];
  94
  95 /// The list of passes run by default.
  96 pub const DEFAULT_PASSES: &[ConditionalPass] = &[
  97     ConditionalPass::always(COLLECT_TRAIT_IMPLS),
  98     ConditionalPass::always(COLLAPSE_DOCS),
  99     ConditionalPass::always(UNINDENT_COMMENTS),
 100     ConditionalPass::always(CHECK_PRIVATE_ITEMS_DOC_TESTS),
 101     ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden),
 102     ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate),
 103     ConditionalPass::new(STRIP_PRIV_IMPORTS, WhenDocumentPrivate),
 104     ConditionalPass::always(COLLECT_INTRA_DOC_LINKS),
 105     ConditionalPass::always(CHECK_CODE_BLOCK_SYNTAX),
 106     ConditionalPass::always(CHECK_INVALID_HTML_TAGS),
 107     ConditionalPass::always(PROPAGATE_DOC_CFG),
 108 ];
 109
 110 /// The list of default passes run when `--doc-coverage` is passed to rustdoc.
 111 pub const COVERAGE_PASSES: &[ConditionalPass] = &[
 112     ConditionalPass::always(COLLECT_TRAIT_IMPLS),
 113     ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden),
 114     ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate),
 115     ConditionalPass::always(CALCULATE_DOC_COVERAGE),
 116 ];
 117
 118 impl ConditionalPass {
 119     pub const fn always(pass: Pass) -> Self {
 120         Self::new(pass, Always)
 121     }
 122
 123     pub const fn new(pass: Pass, condition: Condition) -> Self {
 124         ConditionalPass { pass, condition }
 125     }
 126 }
 127
 128 /// A shorthand way to refer to which set of passes to use, based on the presence of
 129 /// `--no-defaults` and `--show-coverage`.
 130 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 131 pub enum DefaultPassOption {
 132     Default,
 133     Coverage,
 134     None,
 135 }
 136
 137 /// Returns the given default set of passes.
 138 pub fn defaults(default_set: DefaultPassOption) -> &'static [ConditionalPass] {
 139     match default_set {
 140         DefaultPassOption::Default => DEFAULT_PASSES,
 141         DefaultPassOption::Coverage => COVERAGE_PASSES,
 142         DefaultPassOption::None => &[],
 143     }
 144 }
 145
 146 /// If the given name matches a known pass, returns its information.
 147 pub fn find_pass(pass_name: &str) -> Option<Pass> {
 148     PASSES.iter().find(|p| p.name == pass_name).copied()
 149 }
 150
 151 /// Returns a span encompassing all the given attributes.
 152 crate fn span_of_attrs(attrs: &clean::Attributes) -> Option<Span> {
 153     if attrs.doc_strings.is_empty() {
 154         return None;
 155     }
 156     let start = attrs.doc_strings[0].span;
 157     if start == DUMMY_SP {
 158         return None;
 159     }
 160     let end = attrs.doc_strings.last().expect("no doc strings provided").span;
 161     Some(start.to(end))
 162 }
 163
 164 /// Attempts to match a range of bytes from parsed markdown to a `Span` in the source code.
 165 ///
 166 /// This method will return `None` if we cannot construct a span from the source map or if the
 167 /// attributes are not all sugared doc comments. It's difficult to calculate the correct span in
 168 /// that case due to escaping and other source features.
 169 crate fn source_span_for_markdown_range(
 170     cx: &DocContext<'_>,
 171     markdown: &str,
 172     md_range: &Range<usize>,
 173     attrs: &clean::Attributes,
 174 ) -> Option<Span> {
 175     let is_all_sugared_doc =
 176         attrs.doc_strings.iter().all(|frag| frag.kind == DocFragmentKind::SugaredDoc);
 177
 178     if !is_all_sugared_doc {
 179         return None;
 180     }
 181
 182     let snippet = cx.sess().source_map().span_to_snippet(span_of_attrs(attrs)?).ok()?;
 183
 184     let starting_line = markdown[..md_range.start].matches('\n').count();
 185     let ending_line = starting_line + markdown[md_range.start..md_range.end].matches('\n').count();
 186
 187     // We use `split_terminator('\n')` instead of `lines()` when counting bytes so that we treat
 188     // CRLF and LF line endings the same way.
 189     let mut src_lines = snippet.split_terminator('\n');
 190     let md_lines = markdown.split_terminator('\n');
 191
 192     // The number of bytes from the source span to the markdown span that are not part
 193     // of the markdown, like comment markers.
 194     let mut start_bytes = 0;
 195     let mut end_bytes = 0;
 196
 197     'outer: for (line_no, md_line) in md_lines.enumerate() {
 198         loop {
 199             let source_line = src_lines.next().expect("could not find markdown in source");
 200             match source_line.find(md_line) {
 201                 Some(offset) => {
 202                     if line_no == starting_line {
 203                         start_bytes += offset;
 204
 205                         if starting_line == ending_line {
 206                             break 'outer;
 207                         }
 208                     } else if line_no == ending_line {
 209                         end_bytes += offset;
 210                         break 'outer;
 211                     } else if line_no < starting_line {
 212                         start_bytes += source_line.len() - md_line.len();
 213                     } else {
 214                         end_bytes += source_line.len() - md_line.len();
 215                     }
 216                     break;
 217                 }
 218                 None => {
 219                     // Since this is a source line that doesn't include a markdown line,
 220                     // we have to count the newline that we split from earlier.
 221                     if line_no <= starting_line {
 222                         start_bytes += source_line.len() + 1;
 223                     } else {
 224                         end_bytes += source_line.len() + 1;
 225                     }
 226                 }
 227             }
 228         }
 229     }
 230
 231     Some(span_of_attrs(attrs)?.from_inner(InnerSpan::new(
 232         md_range.start + start_bytes,
 233         md_range.end + start_bytes + end_bytes,
 234     )))
 235 }