]>
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; | |
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 | if let Some(ty) = types.node_type_opt(f.hir_id) { | |
146 | (ty, ex.span) | |
147 | } else { | |
148 | trace!("node_type_opt({}) = None", f.hir_id); | |
149 | return; | |
150 | } | |
151 | } | |
152 | hir::ExprKind::MethodCall(_, _, _, span) => { | |
153 | let types = tcx.typeck(ex.hir_id.owner); | |
154 | let def_id = if let Some(def_id) = types.type_dependent_def_id(ex.hir_id) { | |
155 | def_id | |
156 | } else { | |
157 | trace!("type_dependent_def_id({}) = None", ex.hir_id); | |
158 | return; | |
159 | }; | |
160 | (tcx.type_of(def_id), span) | |
161 | } | |
162 | _ => { | |
163 | return; | |
164 | } | |
165 | }; | |
166 | ||
167 | // If this span comes from a macro expansion, then the source code may not actually show | |
168 | // a use of the given item, so it would be a poor example. Hence, we skip all uses in macros. | |
169 | if span.from_expansion() { | |
170 | trace!("Rejecting expr from macro: {:?}", span); | |
171 | return; | |
172 | } | |
173 | ||
174 | // If the enclosing item has a span coming from a proc macro, then we also don't want to include | |
175 | // the example. | |
176 | let enclosing_item_span = tcx.hir().span_with_body(tcx.hir().get_parent_item(ex.hir_id)); | |
177 | if enclosing_item_span.from_expansion() { | |
178 | trace!("Rejecting expr ({:?}) from macro item: {:?}", span, enclosing_item_span); | |
179 | return; | |
180 | } | |
181 | ||
182 | assert!( | |
183 | enclosing_item_span.contains(span), | |
184 | "Attempted to scrape call at [{:?}] whose enclosing item [{:?}] doesn't contain the span of the call.", | |
185 | span, | |
186 | enclosing_item_span | |
187 | ); | |
188 | ||
189 | // Save call site if the function resolves to a concrete definition | |
190 | if let ty::FnDef(def_id, _) = ty.kind() { | |
191 | if self.target_crates.iter().all(|krate| *krate != def_id.krate) { | |
192 | trace!("Rejecting expr from crate not being documented: {:?}", span); | |
193 | return; | |
194 | } | |
195 | ||
196 | let file = tcx.sess.source_map().lookup_char_pos(span.lo()).file; | |
197 | let file_path = match file.name.clone() { | |
198 | FileName::Real(real_filename) => real_filename.into_local_path(), | |
199 | _ => None, | |
200 | }; | |
201 | ||
202 | if let Some(file_path) = file_path { | |
203 | let abs_path = fs::canonicalize(file_path.clone()).unwrap(); | |
204 | let cx = &self.cx; | |
205 | let mk_call_data = || { | |
206 | let clean_span = crate::clean::types::Span::new(span); | |
207 | let url = cx.href_from_span(clean_span, false).unwrap(); | |
208 | let display_name = file_path.display().to_string(); | |
209 | let edition = span.edition(); | |
210 | CallData { locations: Vec::new(), url, display_name, edition } | |
211 | }; | |
212 | ||
213 | let fn_key = tcx.def_path_hash(*def_id); | |
214 | let fn_entries = self.calls.entry(fn_key).or_default(); | |
215 | ||
216 | trace!("Including expr: {:?}", span); | |
217 | let location = CallLocation::new(span, enclosing_item_span, &file); | |
218 | fn_entries.entry(abs_path).or_insert_with(mk_call_data).locations.push(location); | |
219 | } | |
220 | } | |
221 | } | |
222 | } | |
223 | ||
224 | crate fn run( | |
225 | krate: clean::Crate, | |
a2a8927a | 226 | mut renderopts: config::RenderOptions, |
3c0e092e XL |
227 | cache: formats::cache::Cache, |
228 | tcx: TyCtxt<'_>, | |
229 | options: ScrapeExamplesOptions, | |
230 | ) -> interface::Result<()> { | |
231 | let inner = move || -> Result<(), String> { | |
232 | // Generates source files for examples | |
a2a8927a | 233 | renderopts.no_emit_shared = true; |
3c0e092e XL |
234 | let (cx, _) = Context::init(krate, renderopts, cache, tcx).map_err(|e| e.to_string())?; |
235 | ||
236 | // Collect CrateIds corresponding to provided target crates | |
237 | // If two different versions of the crate in the dependency tree, then examples will be collcted from both. | |
238 | let all_crates = tcx | |
239 | .crates(()) | |
240 | .iter() | |
241 | .chain([&LOCAL_CRATE]) | |
242 | .map(|crate_num| (crate_num, tcx.crate_name(*crate_num))) | |
243 | .collect::<Vec<_>>(); | |
244 | let target_crates = options | |
245 | .target_crates | |
246 | .into_iter() | |
247 | .map(|target| all_crates.iter().filter(move |(_, name)| name.as_str() == target)) | |
248 | .flatten() | |
249 | .map(|(crate_num, _)| **crate_num) | |
250 | .collect::<Vec<_>>(); | |
251 | ||
252 | debug!("All crates in TyCtxt: {:?}", all_crates); | |
253 | debug!("Scrape examples target_crates: {:?}", target_crates); | |
254 | ||
255 | // Run call-finder on all items | |
256 | let mut calls = FxHashMap::default(); | |
257 | let mut finder = FindCalls { calls: &mut calls, tcx, map: tcx.hir(), cx, target_crates }; | |
258 | tcx.hir().visit_all_item_likes(&mut finder.as_deep_visitor()); | |
259 | ||
260 | // Sort call locations within a given file in document order | |
261 | for fn_calls in calls.values_mut() { | |
262 | for file_calls in fn_calls.values_mut() { | |
263 | file_calls.locations.sort_by_key(|loc| loc.call_expr.byte_span.0); | |
264 | } | |
265 | } | |
266 | ||
267 | // Save output to provided path | |
268 | let mut encoder = FileEncoder::new(options.output_path).map_err(|e| e.to_string())?; | |
269 | calls.encode(&mut encoder).map_err(|e| e.to_string())?; | |
270 | encoder.flush().map_err(|e| e.to_string())?; | |
271 | ||
272 | Ok(()) | |
273 | }; | |
274 | ||
275 | if let Err(e) = inner() { | |
276 | tcx.sess.fatal(&e); | |
277 | } | |
278 | ||
279 | Ok(()) | |
280 | } | |
281 | ||
282 | // Note: the Handler must be passed in explicitly because sess isn't available while parsing options | |
283 | crate fn load_call_locations( | |
284 | with_examples: Vec<String>, | |
285 | diag: &rustc_errors::Handler, | |
286 | ) -> Result<AllCallLocations, i32> { | |
287 | let inner = || { | |
288 | let mut all_calls: AllCallLocations = FxHashMap::default(); | |
289 | for path in with_examples { | |
290 | let bytes = fs::read(&path).map_err(|e| format!("{} (for path {})", e, path))?; | |
291 | let mut decoder = Decoder::new(&bytes, 0); | |
292 | let calls = AllCallLocations::decode(&mut decoder)?; | |
293 | ||
294 | for (function, fn_calls) in calls.into_iter() { | |
295 | all_calls.entry(function).or_default().extend(fn_calls.into_iter()); | |
296 | } | |
297 | } | |
298 | ||
299 | Ok(all_calls) | |
300 | }; | |
301 | ||
302 | inner().map_err(|e: String| { | |
303 | diag.err(&format!("failed to load examples: {}", e)); | |
304 | 1 | |
305 | }) | |
306 | } |