src/librustdoc/scrape_examples.rs

   1 //! This module analyzes crates to find call sites that can serve as examples in the documentation.
   2
   3 use crate::clean;
   4 use crate::config;
   5 use crate::formats;
   6 use crate::formats::renderer::FormatRenderer;
   7 use crate::html::render::Context;
   8
   9 use rustc_data_structures::fx::FxHashMap;
  10 use rustc_hir::{
  11     self as hir,
  12     intravisit::{self, Visitor},
  13 };
  14 use rustc_interface::interface;
  15 use rustc_macros::{Decodable, Encodable};
  16 use rustc_middle::hir::map::Map;
  17 use rustc_middle::ty::{self, TyCtxt};
  18 use rustc_serialize::{
  19     opaque::{Decoder, FileEncoder},
  20     Decodable, Encodable,
  21 };
  22 use rustc_session::getopts;
  23 use rustc_span::{
  24     def_id::{CrateNum, DefPathHash, LOCAL_CRATE},
  25     edition::Edition,
  26     BytePos, FileName, SourceFile,
  27 };
  28
  29 use std::fs;
  30 use std::path::PathBuf;
  31
  32 #[derive(Debug, Clone)]
  33 crate struct ScrapeExamplesOptions {
  34     output_path: PathBuf,
  35     target_crates: Vec<String>,
  36 }
  37
  38 impl ScrapeExamplesOptions {
  39     crate fn new(
  40         matches: &getopts::Matches,
  41         diag: &rustc_errors::Handler,
  42     ) -> Result<Option<Self>, i32> {
  43         let output_path = matches.opt_str("scrape-examples-output-path");
  44         let target_crates = matches.opt_strs("scrape-examples-target-crate");
  45         match (output_path, !target_crates.is_empty()) {
  46             (Some(output_path), true) => Ok(Some(ScrapeExamplesOptions {
  47                 output_path: PathBuf::from(output_path),
  48                 target_crates,
  49             })),
  50             (Some(_), false) | (None, true) => {
  51                 diag.err("must use --scrape-examples-output-path and --scrape-examples-target-crate together");
  52                 Err(1)
  53             }
  54             (None, false) => Ok(None),
  55         }
  56     }
  57 }
  58
  59 #[derive(Encodable, Decodable, Debug, Clone)]
  60 crate struct SyntaxRange {
  61     crate byte_span: (u32, u32),
  62     crate line_span: (usize, usize),
  63 }
  64
  65 impl SyntaxRange {
  66     fn new(span: rustc_span::Span, file: &SourceFile) -> Self {
  67         let get_pos = |bytepos: BytePos| file.original_relative_byte_pos(bytepos).0;
  68         let get_line = |bytepos: BytePos| file.lookup_line(bytepos).unwrap();
  69
  70         SyntaxRange {
  71             byte_span: (get_pos(span.lo()), get_pos(span.hi())),
  72             line_span: (get_line(span.lo()), get_line(span.hi())),
  73         }
  74     }
  75 }
  76
  77 #[derive(Encodable, Decodable, Debug, Clone)]
  78 crate struct CallLocation {
  79     crate call_expr: SyntaxRange,
  80     crate enclosing_item: SyntaxRange,
  81 }
  82
  83 impl CallLocation {
  84     fn new(
  85         expr_span: rustc_span::Span,
  86         enclosing_item_span: rustc_span::Span,
  87         source_file: &SourceFile,
  88     ) -> Self {
  89         CallLocation {
  90             call_expr: SyntaxRange::new(expr_span, source_file),
  91             enclosing_item: SyntaxRange::new(enclosing_item_span, source_file),
  92         }
  93     }
  94 }
  95
  96 #[derive(Encodable, Decodable, Debug, Clone)]
  97 crate struct CallData {
  98     crate locations: Vec<CallLocation>,
  99     crate url: String,
 100     crate display_name: String,
 101     crate edition: Edition,
 102 }
 103
 104 crate type FnCallLocations = FxHashMap<PathBuf, CallData>;
 105 crate type AllCallLocations = FxHashMap<DefPathHash, FnCallLocations>;
 106
 107 /// Visitor for traversing a crate and finding instances of function calls.
 108 struct FindCalls<'a, 'tcx> {
 109     tcx: TyCtxt<'tcx>,
 110     map: Map<'tcx>,
 111     cx: Context<'tcx>,
 112     target_crates: Vec<CrateNum>,
 113     calls: &'a mut AllCallLocations,
 114 }
 115
 116 impl<'a, 'tcx> Visitor<'tcx> for FindCalls<'a, 'tcx>
 117 where
 118     'tcx: 'a,
 119 {
 120     type Map = Map<'tcx>;
 121
 122     fn nested_visit_map(&mut self) -> intravisit::NestedVisitorMap<Self::Map> {
 123         intravisit::NestedVisitorMap::OnlyBodies(self.map)
 124     }
 125
 126     fn visit_expr(&mut self, ex: &'tcx hir::Expr<'tcx>) {
 127         intravisit::walk_expr(self, ex);
 128
 129         let tcx = self.tcx;
 130
 131         // If we visit an item that contains an expression outside a function body,
 132         // then we need to exit before calling typeck (which will panic). See
 133         // test/run-make/rustdoc-scrape-examples-invalid-expr for an example.
 134         let hir = tcx.hir();
 135         let owner = hir.local_def_id_to_hir_id(ex.hir_id.owner);
 136         if hir.maybe_body_owned_by(owner).is_none() {
 137             return;
 138         }
 139
 140         // Get type of function if expression is a function call
 141         let (ty, span) = match ex.kind {
 142             hir::ExprKind::Call(f, _) => {
 143                 let types = tcx.typeck(ex.hir_id.owner);
 144
 145                 match types.node_type_opt(f.hir_id) {
 146                     Some(ty) => (ty, ex.span),
 147                     None => {
 148                         return;
 149                     }
 150                 }
 151             }
 152             hir::ExprKind::MethodCall(_, _, _, span) => {
 153                 let types = tcx.typeck(ex.hir_id.owner);
 154                 let def_id = types.type_dependent_def_id(ex.hir_id).unwrap();
 155                 (tcx.type_of(def_id), span)
 156             }
 157             _ => {
 158                 return;
 159             }
 160         };
 161
 162         // If this span comes from a macro expansion, then the source code may not actually show
 163         // a use of the given item, so it would be a poor example. Hence, we skip all uses in macros.
 164         if span.from_expansion() {
 165             trace!("Rejecting expr from macro: {:?}", span);
 166             return;
 167         }
 168
 169         // If the enclosing item has a span coming from a proc macro, then we also don't want to include
 170         // the example.
 171         let enclosing_item_span = tcx.hir().span_with_body(tcx.hir().get_parent_item(ex.hir_id));
 172         if enclosing_item_span.from_expansion() {
 173             trace!("Rejecting expr ({:?}) from macro item: {:?}", span, enclosing_item_span);
 174             return;
 175         }
 176
 177         assert!(
 178             enclosing_item_span.contains(span),
 179             "Attempted to scrape call at [{:?}] whose enclosing item [{:?}] doesn't contain the span of the call.",
 180             span,
 181             enclosing_item_span
 182         );
 183
 184         // Save call site if the function resolves to a concrete definition
 185         if let ty::FnDef(def_id, _) = ty.kind() {
 186             if self.target_crates.iter().all(|krate| *krate != def_id.krate) {
 187                 trace!("Rejecting expr from crate not being documented: {:?}", span);
 188                 return;
 189             }
 190
 191             let file = tcx.sess.source_map().lookup_char_pos(span.lo()).file;
 192             let file_path = match file.name.clone() {
 193                 FileName::Real(real_filename) => real_filename.into_local_path(),
 194                 _ => None,
 195             };
 196
 197             if let Some(file_path) = file_path {
 198                 let abs_path = fs::canonicalize(file_path.clone()).unwrap();
 199                 let cx = &self.cx;
 200                 let mk_call_data = || {
 201                     let clean_span = crate::clean::types::Span::new(span);
 202                     let url = cx.href_from_span(clean_span, false).unwrap();
 203                     let display_name = file_path.display().to_string();
 204                     let edition = span.edition();
 205                     CallData { locations: Vec::new(), url, display_name, edition }
 206                 };
 207
 208                 let fn_key = tcx.def_path_hash(*def_id);
 209                 let fn_entries = self.calls.entry(fn_key).or_default();
 210
 211                 trace!("Including expr: {:?}", span);
 212                 let location = CallLocation::new(span, enclosing_item_span, &file);
 213                 fn_entries.entry(abs_path).or_insert_with(mk_call_data).locations.push(location);
 214             }
 215         }
 216     }
 217 }
 218
 219 crate fn run(
 220     krate: clean::Crate,
 221     renderopts: config::RenderOptions,
 222     cache: formats::cache::Cache,
 223     tcx: TyCtxt<'_>,
 224     options: ScrapeExamplesOptions,
 225 ) -> interface::Result<()> {
 226     let inner = move || -> Result<(), String> {
 227         // Generates source files for examples
 228         let (cx, _) = Context::init(krate, renderopts, cache, tcx).map_err(|e| e.to_string())?;
 229
 230         // Collect CrateIds corresponding to provided target crates
 231         // If two different versions of the crate in the dependency tree, then examples will be collcted from both.
 232         let all_crates = tcx
 233             .crates(())
 234             .iter()
 235             .chain([&LOCAL_CRATE])
 236             .map(|crate_num| (crate_num, tcx.crate_name(*crate_num)))
 237             .collect::<Vec<_>>();
 238         let target_crates = options
 239             .target_crates
 240             .into_iter()
 241             .map(|target| all_crates.iter().filter(move |(_, name)| name.as_str() == target))
 242             .flatten()
 243             .map(|(crate_num, _)| **crate_num)
 244             .collect::<Vec<_>>();
 245
 246         debug!("All crates in TyCtxt: {:?}", all_crates);
 247         debug!("Scrape examples target_crates: {:?}", target_crates);
 248
 249         // Run call-finder on all items
 250         let mut calls = FxHashMap::default();
 251         let mut finder = FindCalls { calls: &mut calls, tcx, map: tcx.hir(), cx, target_crates };
 252         tcx.hir().visit_all_item_likes(&mut finder.as_deep_visitor());
 253
 254         // Sort call locations within a given file in document order
 255         for fn_calls in calls.values_mut() {
 256             for file_calls in fn_calls.values_mut() {
 257                 file_calls.locations.sort_by_key(|loc| loc.call_expr.byte_span.0);
 258             }
 259         }
 260
 261         // Save output to provided path
 262         let mut encoder = FileEncoder::new(options.output_path).map_err(|e| e.to_string())?;
 263         calls.encode(&mut encoder).map_err(|e| e.to_string())?;
 264         encoder.flush().map_err(|e| e.to_string())?;
 265
 266         Ok(())
 267     };
 268
 269     if let Err(e) = inner() {
 270         tcx.sess.fatal(&e);
 271     }
 272
 273     Ok(())
 274 }
 275
 276 // Note: the Handler must be passed in explicitly because sess isn't available while parsing options
 277 crate fn load_call_locations(
 278     with_examples: Vec<String>,
 279     diag: &rustc_errors::Handler,
 280 ) -> Result<AllCallLocations, i32> {
 281     let inner = || {
 282         let mut all_calls: AllCallLocations = FxHashMap::default();
 283         for path in with_examples {
 284             let bytes = fs::read(&path).map_err(|e| format!("{} (for path {})", e, path))?;
 285             let mut decoder = Decoder::new(&bytes, 0);
 286             let calls = AllCallLocations::decode(&mut decoder)?;
 287
 288             for (function, fn_calls) in calls.into_iter() {
 289                 all_calls.entry(function).or_default().extend(fn_calls.into_iter());
 290             }
 291         }
 292
 293         Ok(all_calls)
 294     };
 295
 296     inner().map_err(|e: String| {
 297         diag.err(&format!("failed to load examples: {}", e));
 298         1
 299     })
 300 }