rustdoc/
scrape_examples.rs

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