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