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 bare_urls;
  16 crate use self::bare_urls::CHECK_BARE_URLS;
  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 crate 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_BARE_URLS,
  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_BARE_URLS),
 109 ];
 110
 111 /// The list of default passes run when `--doc-coverage` is passed to rustdoc.
 112 crate const COVERAGE_PASSES: &[ConditionalPass] = &[
 113     ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden),
 114     ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate),
 115     ConditionalPass::always(CALCULATE_DOC_COVERAGE),
 116 ];
 117
 118 impl ConditionalPass {
 119     crate const fn always(pass: Pass) -> Self {
 120         Self::new(pass, Always)
 121     }
 122
 123     crate 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 crate enum DefaultPassOption {
 132     Default,
 133     Coverage,
 134     None,
 135 }
 136
 137 /// Returns the given default set of passes.
 138 crate 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 crate 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     tcx: TyCtxt<'_>,
 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 = tcx.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 }