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