src/librustdoc/passes/mod.rs

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