rustdoc/doctest/
rust.rs

1//! Doctest functionality used only for doctests in `.rs` source files.
2
3use std::cell::Cell;
4use std::str::FromStr;
5use std::sync::Arc;
6
7use proc_macro2::{TokenStream, TokenTree};
8use rustc_attr_parsing::eval_config_entry;
9use rustc_hir::attrs::AttributeKind;
10use rustc_hir::def_id::{CRATE_DEF_ID, LocalDefId};
11use rustc_hir::{self as hir, Attribute, CRATE_HIR_ID, intravisit};
12use rustc_middle::hir::nested_filter;
13use rustc_middle::ty::TyCtxt;
14use rustc_resolve::rustdoc::span_of_fragments;
15use rustc_span::source_map::SourceMap;
16use rustc_span::{BytePos, DUMMY_SP, FileName, Pos, Span};
17
18use super::{DocTestVisitor, ScrapedDocTest};
19use crate::clean::{Attributes, CfgInfo, extract_cfg_from_attrs};
20use crate::html::markdown::{self, ErrorCodes, LangString, MdRelLine};
21
22struct RustCollector {
23    source_map: Arc<SourceMap>,
24    tests: Vec<ScrapedDocTest>,
25    cur_path: Vec<String>,
26    position: Span,
27    global_crate_attrs: Vec<String>,
28}
29
30impl RustCollector {
31    fn get_filename(&self) -> FileName {
32        let filename = self.source_map.span_to_filename(self.position);
33        filename
34    }
35
36    fn get_base_line(&self) -> usize {
37        let sp_lo = self.position.lo().to_usize();
38        let loc = self.source_map.lookup_char_pos(BytePos(sp_lo as u32));
39        loc.line
40    }
41}
42
43impl DocTestVisitor for RustCollector {
44    fn visit_test(&mut self, test: String, config: LangString, rel_line: MdRelLine) {
45        let base_line = self.get_base_line();
46        let line = base_line + rel_line.offset();
47        let count = Cell::new(base_line);
48        let span = if line > base_line {
49            match self.source_map.span_extend_while(self.position, |c| {
50                if c == '\n' {
51                    let count_v = count.get();
52                    count.set(count_v + 1);
53                    if count_v >= line {
54                        return false;
55                    }
56                }
57                true
58            }) {
59                Ok(sp) => self.source_map.span_extend_to_line(sp.shrink_to_hi()),
60                _ => self.position,
61            }
62        } else {
63            self.position
64        };
65        self.tests.push(ScrapedDocTest::new(
66            self.get_filename(),
67            line,
68            self.cur_path.clone(),
69            config,
70            test,
71            span,
72            self.global_crate_attrs.clone(),
73        ));
74    }
75
76    fn visit_header(&mut self, _name: &str, _level: u32) {}
77}
78
79pub(super) struct HirCollector<'tcx> {
80    codes: ErrorCodes,
81    tcx: TyCtxt<'tcx>,
82    collector: RustCollector,
83}
84
85impl<'tcx> HirCollector<'tcx> {
86    pub fn new(codes: ErrorCodes, tcx: TyCtxt<'tcx>) -> Self {
87        let collector = RustCollector {
88            source_map: tcx.sess.psess.clone_source_map(),
89            cur_path: vec![],
90            position: DUMMY_SP,
91            tests: vec![],
92            global_crate_attrs: Vec::new(),
93        };
94        Self { codes, tcx, collector }
95    }
96
97    pub fn collect_crate(mut self) -> Vec<ScrapedDocTest> {
98        let tcx = self.tcx;
99        self.visit_testable(None, CRATE_DEF_ID, tcx.hir_span(CRATE_HIR_ID), |this| {
100            tcx.hir_walk_toplevel_module(this)
101        });
102        self.collector.tests
103    }
104}
105
106impl HirCollector<'_> {
107    fn visit_testable<F: FnOnce(&mut Self)>(
108        &mut self,
109        name: Option<String>,
110        def_id: LocalDefId,
111        sp: Span,
112        nested: F,
113    ) {
114        let ast_attrs = self.tcx.hir_attrs(self.tcx.local_def_id_to_hir_id(def_id));
115        if let Some(ref cfg) =
116            extract_cfg_from_attrs(ast_attrs.iter(), self.tcx, &mut CfgInfo::default())
117            && !eval_config_entry(&self.tcx.sess, cfg.inner()).as_bool()
118        {
119            return;
120        }
121
122        let source_map = self.tcx.sess.source_map();
123        // Try collecting `#[doc(test(attr(...)))]`
124        let old_global_crate_attrs_len = self.collector.global_crate_attrs.len();
125        for attr in ast_attrs {
126            let Attribute::Parsed(AttributeKind::Doc(d)) = attr else { continue };
127            for attr_span in &d.test_attrs {
128                // FIXME: This is ugly, remove when `test_attrs` has been ported to new attribute API.
129                if let Ok(snippet) = source_map.span_to_snippet(*attr_span)
130                    && let Ok(stream) = TokenStream::from_str(&snippet)
131                {
132                    let mut iter = stream.into_iter().peekable();
133                    while let Some(token) = iter.next() {
134                        if let TokenTree::Ident(i) = token {
135                            let i = i.to_string();
136                            let peek = iter.peek();
137                            // From this ident, we can have things like:
138                            //
139                            // * Group: `allow(...)`
140                            // * Name/value: `crate_name = "..."`
141                            // * Tokens: `html_no_url`
142                            //
143                            // So we peek next element to know what case we are in.
144                            match peek {
145                                Some(TokenTree::Group(g)) => {
146                                    let g = g.to_string();
147                                    iter.next();
148                                    // Add the additional attributes to the global_crate_attrs vector
149                                    self.collector.global_crate_attrs.push(format!("{i}{g}"));
150                                }
151                                // If next item is `=`, it means it's a name value so we will need
152                                // to get the value as well.
153                                Some(TokenTree::Punct(p)) if p.as_char() == '=' => {
154                                    let p = p.to_string();
155                                    iter.next();
156                                    if let Some(last) = iter.next() {
157                                        // Add the additional attributes to the global_crate_attrs vector
158                                        self.collector
159                                            .global_crate_attrs
160                                            .push(format!("{i}{p}{last}"));
161                                    }
162                                }
163                                _ => {
164                                    // Add the additional attributes to the global_crate_attrs vector
165                                    self.collector.global_crate_attrs.push(i.to_string());
166                                }
167                            }
168                        }
169                    }
170                }
171            }
172        }
173
174        let mut has_name = false;
175        if let Some(name) = name {
176            self.collector.cur_path.push(name);
177            has_name = true;
178        }
179
180        // The collapse-docs pass won't combine sugared/raw doc attributes, or included files with
181        // anything else, this will combine them for us.
182        let attrs = Attributes::from_hir(ast_attrs);
183        if let Some(doc) = attrs.opt_doc_value() {
184            let span = span_of_fragments(&attrs.doc_strings).unwrap_or(sp);
185            self.collector.position = if span.edition().at_least_rust_2024() {
186                span
187            } else {
188                // this span affects filesystem path resolution,
189                // so we need to keep it the same as it was previously
190                ast_attrs
191                    .iter()
192                    .find(|attr| attr.doc_str().is_some())
193                    .map(|attr| {
194                        attr.span().ctxt().outer_expn().expansion_cause().unwrap_or(attr.span())
195                    })
196                    .unwrap_or(DUMMY_SP)
197            };
198            markdown::find_testable_code(
199                &doc,
200                &mut self.collector,
201                self.codes,
202                Some(&crate::html::markdown::ExtraInfo::new(self.tcx, def_id, span)),
203            );
204        }
205
206        nested(self);
207
208        // Restore global_crate_attrs to it's previous size/content
209        self.collector.global_crate_attrs.truncate(old_global_crate_attrs_len);
210
211        if has_name {
212            self.collector.cur_path.pop();
213        }
214    }
215}
216
217impl<'tcx> intravisit::Visitor<'tcx> for HirCollector<'tcx> {
218    type NestedFilter = nested_filter::All;
219
220    fn maybe_tcx(&mut self) -> Self::MaybeTyCtxt {
221        self.tcx
222    }
223
224    fn visit_item(&mut self, item: &'tcx hir::Item<'_>) {
225        let name = match &item.kind {
226            hir::ItemKind::Impl(impl_) => {
227                Some(rustc_hir_pretty::id_to_string(&self.tcx, impl_.self_ty.hir_id))
228            }
229            _ => item.kind.ident().map(|ident| ident.to_string()),
230        };
231
232        self.visit_testable(name, item.owner_id.def_id, item.span, |this| {
233            intravisit::walk_item(this, item);
234        });
235    }
236
237    fn visit_trait_item(&mut self, item: &'tcx hir::TraitItem<'_>) {
238        self.visit_testable(
239            Some(item.ident.to_string()),
240            item.owner_id.def_id,
241            item.span,
242            |this| {
243                intravisit::walk_trait_item(this, item);
244            },
245        );
246    }
247
248    fn visit_impl_item(&mut self, item: &'tcx hir::ImplItem<'_>) {
249        self.visit_testable(
250            Some(item.ident.to_string()),
251            item.owner_id.def_id,
252            item.span,
253            |this| {
254                intravisit::walk_impl_item(this, item);
255            },
256        );
257    }
258
259    fn visit_foreign_item(&mut self, item: &'tcx hir::ForeignItem<'_>) {
260        self.visit_testable(
261            Some(item.ident.to_string()),
262            item.owner_id.def_id,
263            item.span,
264            |this| {
265                intravisit::walk_foreign_item(this, item);
266            },
267        );
268    }
269
270    fn visit_variant(&mut self, v: &'tcx hir::Variant<'_>) {
271        self.visit_testable(Some(v.ident.to_string()), v.def_id, v.span, |this| {
272            intravisit::walk_variant(this, v);
273        });
274    }
275
276    fn visit_field_def(&mut self, f: &'tcx hir::FieldDef<'_>) {
277        self.visit_testable(Some(f.ident.to_string()), f.def_id, f.span, |this| {
278            intravisit::walk_field_def(this, f);
279        });
280    }
281}
rustdoc/doctest/rust.rs

rustdoc/doctest/
rust.rs
