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