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 check_doc_test_visibility;
  37 crate use self::check_doc_test_visibility::CHECK_DOC_TEST_VISIBILITY;
  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_DOC_TEST_VISIBILITY,
  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_DOC_TEST_VISIBILITY),
 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 /// Returns the given default set of passes.
 129 crate fn defaults(show_coverage: bool) -> &'static [ConditionalPass] {
 130     if show_coverage { COVERAGE_PASSES } else { DEFAULT_PASSES }
 131 }
 132
 133 /// Returns a span encompassing all the given attributes.
 134 crate fn span_of_attrs(attrs: &clean::Attributes) -> Option<Span> {
 135     if attrs.doc_strings.is_empty() {
 136         return None;
 137     }
 138     let start = attrs.doc_strings[0].span;
 139     if start == DUMMY_SP {
 140         return None;
 141     }
 142     let end = attrs.doc_strings.last().expect("no doc strings provided").span;
 143     Some(start.to(end))
 144 }
 145
 146 /// Attempts to match a range of bytes from parsed markdown to a `Span` in the source code.
 147 ///
 148 /// This method will return `None` if we cannot construct a span from the source map or if the
 149 /// attributes are not all sugared doc comments. It's difficult to calculate the correct span in
 150 /// that case due to escaping and other source features.
 151 crate fn source_span_for_markdown_range(
 152     tcx: TyCtxt<'_>,
 153     markdown: &str,
 154     md_range: &Range<usize>,
 155     attrs: &clean::Attributes,
 156 ) -> Option<Span> {
 157     let is_all_sugared_doc =
 158         attrs.doc_strings.iter().all(|frag| frag.kind == DocFragmentKind::SugaredDoc);
 159
 160     if !is_all_sugared_doc {
 161         return None;
 162     }
 163
 164     let snippet = tcx.sess.source_map().span_to_snippet(span_of_attrs(attrs)?).ok()?;
 165
 166     let starting_line = markdown[..md_range.start].matches('\n').count();
 167     let ending_line = starting_line + markdown[md_range.start..md_range.end].matches('\n').count();
 168
 169     // We use `split_terminator('\n')` instead of `lines()` when counting bytes so that we treat
 170     // CRLF and LF line endings the same way.
 171     let mut src_lines = snippet.split_terminator('\n');
 172     let md_lines = markdown.split_terminator('\n');
 173
 174     // The number of bytes from the source span to the markdown span that are not part
 175     // of the markdown, like comment markers.
 176     let mut start_bytes = 0;
 177     let mut end_bytes = 0;
 178
 179     'outer: for (line_no, md_line) in md_lines.enumerate() {
 180         loop {
 181             let source_line = src_lines.next().expect("could not find markdown in source");
 182             match source_line.find(md_line) {
 183                 Some(offset) => {
 184                     if line_no == starting_line {
 185                         start_bytes += offset;
 186
 187                         if starting_line == ending_line {
 188                             break 'outer;
 189                         }
 190                     } else if line_no == ending_line {
 191                         end_bytes += offset;
 192                         break 'outer;
 193                     } else if line_no < starting_line {
 194                         start_bytes += source_line.len() - md_line.len();
 195                     } else {
 196                         end_bytes += source_line.len() - md_line.len();
 197                     }
 198                     break;
 199                 }
 200                 None => {
 201                     // Since this is a source line that doesn't include a markdown line,
 202                     // we have to count the newline that we split from earlier.
 203                     if line_no <= starting_line {
 204                         start_bytes += source_line.len() + 1;
 205                     } else {
 206                         end_bytes += source_line.len() + 1;
 207                     }
 208                 }
 209             }
 210         }
 211     }
 212
 213     Some(span_of_attrs(attrs)?.from_inner(InnerSpan::new(
 214         md_range.start + start_bytes,
 215         md_range.end + start_bytes + end_bytes,
 216     )))
 217 }