]> git.lizzy.rs Git - rust.git/blob - src/librustdoc/visit_ast.rs
Rollup merge of #60766 - vorner:weak-into-raw, r=sfackler
[rust.git] / src / librustdoc / visit_ast.rs
1 //! The Rust AST Visitor. Extracts useful information and massages it into a form
2 //! usable for `clean`.
3
4 use rustc::hir::{self, Node};
5 use rustc::hir::def::{Res, DefKind};
6 use rustc::hir::def_id::{DefId, LOCAL_CRATE};
7 use rustc::middle::privacy::AccessLevel;
8 use rustc::util::nodemap::{FxHashSet, FxHashMap};
9 use syntax::ast;
10 use syntax::attr;
11 use syntax::ext::base::MacroKind;
12 use syntax::source_map::Spanned;
13 use syntax::symbol::sym;
14 use syntax_pos::{self, Span};
15
16 use std::mem;
17
18 use crate::core;
19 use crate::clean::{self, AttributesExt, NestedAttributesExt, def_id_to_path};
20 use crate::doctree::*;
21
22
23 // Looks to me like the first two of these are actually
24 // output parameters, maybe only mutated once; perhaps
25 // better simply to have the visit method return a tuple
26 // containing them?
27
28 // Also, is there some reason that this doesn't use the 'visit'
29 // framework from syntax?.
30
31 pub struct RustdocVisitor<'a, 'tcx> {
32     pub module: Module,
33     pub attrs: hir::HirVec<ast::Attribute>,
34     pub cx: &'a core::DocContext<'tcx>,
35     view_item_stack: FxHashSet<hir::HirId>,
36     inlining: bool,
37     /// Are the current module and all of its parents public?
38     inside_public_path: bool,
39     exact_paths: Option<FxHashMap<DefId, Vec<String>>>,
40 }
41
42 impl<'a, 'tcx> RustdocVisitor<'a, 'tcx> {
43     pub fn new(
44         cx: &'a core::DocContext<'tcx>
45     ) -> RustdocVisitor<'a, 'tcx> {
46         // If the root is re-exported, terminate all recursion.
47         let mut stack = FxHashSet::default();
48         stack.insert(hir::CRATE_HIR_ID);
49         RustdocVisitor {
50             module: Module::new(None),
51             attrs: hir::HirVec::new(),
52             cx,
53             view_item_stack: stack,
54             inlining: false,
55             inside_public_path: true,
56             exact_paths: Some(FxHashMap::default()),
57         }
58     }
59
60     fn store_path(&mut self, did: DefId) {
61         // We can't use the entry API, as that keeps the mutable borrow of `self` active
62         // when we try to use `cx`.
63         let exact_paths = self.exact_paths.as_mut().unwrap();
64         if exact_paths.get(&did).is_none() {
65             let path = def_id_to_path(self.cx, did, self.cx.crate_name.clone());
66             exact_paths.insert(did, path);
67         }
68     }
69
70     fn stability(&self, id: hir::HirId) -> Option<attr::Stability> {
71         self.cx.tcx.hir().opt_local_def_id_from_hir_id(id)
72             .and_then(|def_id| self.cx.tcx.lookup_stability(def_id)).cloned()
73     }
74
75     fn deprecation(&self, id: hir::HirId) -> Option<attr::Deprecation> {
76         self.cx.tcx.hir().opt_local_def_id_from_hir_id(id)
77             .and_then(|def_id| self.cx.tcx.lookup_deprecation(def_id))
78     }
79
80     pub fn visit(&mut self, krate: &hir::Crate) {
81         self.attrs = krate.attrs.clone();
82
83         self.module = self.visit_mod_contents(krate.span,
84                                               krate.attrs.clone(),
85                                               Spanned { span: syntax_pos::DUMMY_SP,
86                                                         node: hir::VisibilityKind::Public },
87                                               hir::CRATE_HIR_ID,
88                                               &krate.module,
89                                               None);
90         // Attach the crate's exported macros to the top-level module:
91         let macro_exports: Vec<_> =
92             krate.exported_macros.iter().map(|def| self.visit_local_macro(def, None)).collect();
93         self.module.macros.extend(macro_exports);
94         self.module.is_crate = true;
95
96         self.cx.renderinfo.borrow_mut().exact_paths = self.exact_paths.take().unwrap();
97     }
98
99     pub fn visit_variant_data(&mut self, item: &hir::Item,
100                               name: ast::Name, sd: &hir::VariantData,
101                               generics: &hir::Generics) -> Struct {
102         debug!("Visiting struct");
103         let struct_type = struct_type_from_def(&*sd);
104         Struct {
105             id: item.hir_id,
106             struct_type,
107             name,
108             vis: item.vis.clone(),
109             stab: self.stability(item.hir_id),
110             depr: self.deprecation(item.hir_id),
111             attrs: item.attrs.clone(),
112             generics: generics.clone(),
113             fields: sd.fields().iter().cloned().collect(),
114             whence: item.span
115         }
116     }
117
118     pub fn visit_union_data(&mut self, item: &hir::Item,
119                             name: ast::Name, sd: &hir::VariantData,
120                             generics: &hir::Generics) -> Union {
121         debug!("Visiting union");
122         let struct_type = struct_type_from_def(&*sd);
123         Union {
124             id: item.hir_id,
125             struct_type,
126             name,
127             vis: item.vis.clone(),
128             stab: self.stability(item.hir_id),
129             depr: self.deprecation(item.hir_id),
130             attrs: item.attrs.clone(),
131             generics: generics.clone(),
132             fields: sd.fields().iter().cloned().collect(),
133             whence: item.span
134         }
135     }
136
137     pub fn visit_enum_def(&mut self, it: &hir::Item,
138                           name: ast::Name, def: &hir::EnumDef,
139                           params: &hir::Generics) -> Enum {
140         debug!("Visiting enum");
141         Enum {
142             name,
143             variants: def.variants.iter().map(|v| Variant {
144                 name: v.node.ident.name,
145                 id: v.node.id,
146                 attrs: v.node.attrs.clone(),
147                 stab: self.stability(v.node.id),
148                 depr: self.deprecation(v.node.id),
149                 def: v.node.data.clone(),
150                 whence: v.span,
151             }).collect(),
152             vis: it.vis.clone(),
153             stab: self.stability(it.hir_id),
154             depr: self.deprecation(it.hir_id),
155             generics: params.clone(),
156             attrs: it.attrs.clone(),
157             id: it.hir_id,
158             whence: it.span,
159         }
160     }
161
162     pub fn visit_fn(&mut self, om: &mut Module, item: &hir::Item,
163                     name: ast::Name, fd: &hir::FnDecl,
164                     header: hir::FnHeader,
165                     gen: &hir::Generics,
166                     body: hir::BodyId) {
167         debug!("Visiting fn");
168         let macro_kind = item.attrs.iter().filter_map(|a| {
169             if a.check_name(sym::proc_macro) {
170                 Some(MacroKind::Bang)
171             } else if a.check_name(sym::proc_macro_derive) {
172                 Some(MacroKind::Derive)
173             } else if a.check_name(sym::proc_macro_attribute) {
174                 Some(MacroKind::Attr)
175             } else {
176                 None
177             }
178         }).next();
179         match macro_kind {
180             Some(kind) => {
181                 let name = if kind == MacroKind::Derive {
182                     item.attrs.lists(sym::proc_macro_derive)
183                               .filter_map(|mi| mi.ident())
184                               .next()
185                               .expect("proc-macro derives require a name")
186                               .name
187                 } else {
188                     name
189                 };
190
191                 let mut helpers = Vec::new();
192                 for mi in item.attrs.lists(sym::proc_macro_derive) {
193                     if !mi.check_name(sym::attributes) {
194                         continue;
195                     }
196
197                     if let Some(list) = mi.meta_item_list() {
198                         for inner_mi in list {
199                             if let Some(ident) = inner_mi.ident() {
200                                 helpers.push(ident.name);
201                             }
202                         }
203                     }
204                 }
205
206                 om.proc_macros.push(ProcMacro {
207                     name,
208                     id: item.hir_id,
209                     kind,
210                     helpers,
211                     attrs: item.attrs.clone(),
212                     whence: item.span,
213                     stab: self.stability(item.hir_id),
214                     depr: self.deprecation(item.hir_id),
215                 });
216             }
217             None => {
218                 om.fns.push(Function {
219                     id: item.hir_id,
220                     vis: item.vis.clone(),
221                     stab: self.stability(item.hir_id),
222                     depr: self.deprecation(item.hir_id),
223                     attrs: item.attrs.clone(),
224                     decl: fd.clone(),
225                     name,
226                     whence: item.span,
227                     generics: gen.clone(),
228                     header,
229                     body,
230                 });
231             }
232         }
233     }
234
235     pub fn visit_mod_contents(&mut self, span: Span, attrs: hir::HirVec<ast::Attribute>,
236                               vis: hir::Visibility, id: hir::HirId,
237                               m: &hir::Mod,
238                               name: Option<ast::Name>) -> Module {
239         let mut om = Module::new(name);
240         om.where_outer = span;
241         om.where_inner = m.inner;
242         om.attrs = attrs;
243         om.vis = vis.clone();
244         om.stab = self.stability(id);
245         om.depr = self.deprecation(id);
246         om.id = self.cx.tcx.hir().hir_to_node_id(id);
247         // Keep track of if there were any private modules in the path.
248         let orig_inside_public_path = self.inside_public_path;
249         self.inside_public_path &= vis.node.is_pub();
250         for i in &m.item_ids {
251             let item = self.cx.tcx.hir().expect_item_by_hir_id(i.id);
252             self.visit_item(item, None, &mut om);
253         }
254         self.inside_public_path = orig_inside_public_path;
255         om
256     }
257
258     /// Tries to resolve the target of a `pub use` statement and inlines the
259     /// target if it is defined locally and would not be documented otherwise,
260     /// or when it is specifically requested with `please_inline`.
261     /// (the latter is the case when the import is marked `doc(inline)`)
262     ///
263     /// Cross-crate inlining occurs later on during crate cleaning
264     /// and follows different rules.
265     ///
266     /// Returns `true` if the target has been inlined.
267     fn maybe_inline_local(&mut self,
268                           id: hir::HirId,
269                           res: Res,
270                           renamed: Option<ast::Ident>,
271                           glob: bool,
272                           om: &mut Module,
273                           please_inline: bool) -> bool {
274
275         fn inherits_doc_hidden(cx: &core::DocContext<'_>, mut node: hir::HirId) -> bool {
276             while let Some(id) = cx.tcx.hir().get_enclosing_scope(node) {
277                 node = id;
278                 if cx.tcx.hir().attrs_by_hir_id(node)
279                     .lists(sym::doc).has_word(sym::hidden) {
280                     return true;
281                 }
282                 if node == hir::CRATE_HIR_ID {
283                     break;
284                 }
285             }
286             false
287         }
288
289         debug!("maybe_inline_local res: {:?}", res);
290
291         let tcx = self.cx.tcx;
292         let res_did = if let Some(did) = res.opt_def_id() {
293             did
294         } else {
295             return false;
296         };
297
298         let use_attrs = tcx.hir().attrs_by_hir_id(id);
299         // Don't inline `doc(hidden)` imports so they can be stripped at a later stage.
300         let is_no_inline = use_attrs.lists(sym::doc).has_word(sym::no_inline) ||
301                            use_attrs.lists(sym::doc).has_word(sym::hidden);
302
303         // For cross-crate impl inlining we need to know whether items are
304         // reachable in documentation -- a previously nonreachable item can be
305         // made reachable by cross-crate inlining which we're checking here.
306         // (this is done here because we need to know this upfront).
307         if !res_did.is_local() && !is_no_inline {
308             let attrs = clean::inline::load_attrs(self.cx, res_did);
309             let self_is_hidden = attrs.lists(sym::doc).has_word(sym::hidden);
310             match res {
311                 Res::Def(DefKind::Trait, did) |
312                 Res::Def(DefKind::Struct, did) |
313                 Res::Def(DefKind::Union, did) |
314                 Res::Def(DefKind::Enum, did) |
315                 Res::Def(DefKind::ForeignTy, did) |
316                 Res::Def(DefKind::TyAlias, did) if !self_is_hidden => {
317                     self.cx.renderinfo
318                         .borrow_mut()
319                         .access_levels.map
320                         .insert(did, AccessLevel::Public);
321                 },
322                 Res::Def(DefKind::Mod, did) => if !self_is_hidden {
323                     crate::visit_lib::LibEmbargoVisitor::new(self.cx).visit_mod(did);
324                 },
325                 _ => {},
326             }
327
328             return false
329         }
330
331         let res_hir_id = match tcx.hir().as_local_hir_id(res_did) {
332             Some(n) => n, None => return false
333         };
334
335         let is_private = !self.cx.renderinfo.borrow().access_levels.is_public(res_did);
336         let is_hidden = inherits_doc_hidden(self.cx, res_hir_id);
337
338         // Only inline if requested or if the item would otherwise be stripped.
339         if (!please_inline && !is_private && !is_hidden) || is_no_inline {
340             return false
341         }
342
343         if !self.view_item_stack.insert(res_hir_id) { return false }
344
345         let ret = match tcx.hir().get_by_hir_id(res_hir_id) {
346             Node::Item(&hir::Item { node: hir::ItemKind::Mod(ref m), .. }) if glob => {
347                 let prev = mem::replace(&mut self.inlining, true);
348                 for i in &m.item_ids {
349                     let i = self.cx.tcx.hir().expect_item_by_hir_id(i.id);
350                     self.visit_item(i, None, om);
351                 }
352                 self.inlining = prev;
353                 true
354             }
355             Node::Item(it) if !glob => {
356                 let prev = mem::replace(&mut self.inlining, true);
357                 self.visit_item(it, renamed, om);
358                 self.inlining = prev;
359                 true
360             }
361             Node::ForeignItem(it) if !glob => {
362                 // Generate a fresh `extern {}` block if we want to inline a foreign item.
363                 om.foreigns.push(hir::ForeignMod {
364                     abi: tcx.hir().get_foreign_abi_by_hir_id(it.hir_id),
365                     items: vec![hir::ForeignItem {
366                         ident: renamed.unwrap_or(it.ident),
367                         .. it.clone()
368                     }].into(),
369                 });
370                 true
371             }
372             Node::MacroDef(def) if !glob => {
373                 om.macros.push(self.visit_local_macro(def, renamed.map(|i| i.name)));
374                 true
375             }
376             _ => false,
377         };
378         self.view_item_stack.remove(&res_hir_id);
379         ret
380     }
381
382     pub fn visit_item(&mut self, item: &hir::Item,
383                       renamed: Option<ast::Ident>, om: &mut Module) {
384         debug!("Visiting item {:?}", item);
385         let ident = renamed.unwrap_or(item.ident);
386
387         if item.vis.node.is_pub() {
388             let def_id = self.cx.tcx.hir().local_def_id_from_hir_id(item.hir_id);
389             self.store_path(def_id);
390         }
391
392         match item.node {
393             hir::ItemKind::ForeignMod(ref fm) => {
394                 // If inlining we only want to include public functions.
395                 om.foreigns.push(if self.inlining {
396                     hir::ForeignMod {
397                         abi: fm.abi,
398                         items: fm.items.iter().filter(|i| i.vis.node.is_pub()).cloned().collect(),
399                     }
400                 } else {
401                     fm.clone()
402                 });
403             }
404             // If we're inlining, skip private items.
405             _ if self.inlining && !item.vis.node.is_pub() => {}
406             hir::ItemKind::GlobalAsm(..) => {}
407             hir::ItemKind::ExternCrate(orig_name) => {
408                 let def_id = self.cx.tcx.hir().local_def_id_from_hir_id(item.hir_id);
409                 om.extern_crates.push(ExternCrate {
410                     cnum: self.cx.tcx.extern_mod_stmt_cnum(def_id)
411                                 .unwrap_or(LOCAL_CRATE),
412                     name: ident.name,
413                     path: orig_name.map(|x|x.to_string()),
414                     vis: item.vis.clone(),
415                     attrs: item.attrs.clone(),
416                     whence: item.span,
417                 })
418             }
419             hir::ItemKind::Use(_, hir::UseKind::ListStem) => {}
420             hir::ItemKind::Use(ref path, kind) => {
421                 let is_glob = kind == hir::UseKind::Glob;
422
423                 // Struct and variant constructors and proc macro stubs always show up alongside
424                 // their definitions, we've already processed them so just discard these.
425                 match path.res {
426                     Res::Def(DefKind::Ctor(..), _)
427                     | Res::SelfCtor(..)
428                     | Res::Def(DefKind::Macro(MacroKind::ProcMacroStub), _) => return,
429                     _ => {}
430                 }
431
432                 // If there was a private module in the current path then don't bother inlining
433                 // anything as it will probably be stripped anyway.
434                 if item.vis.node.is_pub() && self.inside_public_path {
435                     let please_inline = item.attrs.iter().any(|item| {
436                         match item.meta_item_list() {
437                             Some(ref list) if item.check_name(sym::doc) => {
438                                 list.iter().any(|i| i.check_name(sym::inline))
439                             }
440                             _ => false,
441                         }
442                     });
443                     let ident = if is_glob { None } else { Some(ident) };
444                     if self.maybe_inline_local(item.hir_id,
445                                                path.res,
446                                                ident,
447                                                is_glob,
448                                                om,
449                                                please_inline) {
450                         return;
451                     }
452                 }
453
454                 om.imports.push(Import {
455                     name: ident.name,
456                     id: item.hir_id,
457                     vis: item.vis.clone(),
458                     attrs: item.attrs.clone(),
459                     path: (**path).clone(),
460                     glob: is_glob,
461                     whence: item.span,
462                 });
463             }
464             hir::ItemKind::Mod(ref m) => {
465                 om.mods.push(self.visit_mod_contents(item.span,
466                                                      item.attrs.clone(),
467                                                      item.vis.clone(),
468                                                      item.hir_id,
469                                                      m,
470                                                      Some(ident.name)));
471             },
472             hir::ItemKind::Enum(ref ed, ref gen) =>
473                 om.enums.push(self.visit_enum_def(item, ident.name, ed, gen)),
474             hir::ItemKind::Struct(ref sd, ref gen) =>
475                 om.structs.push(self.visit_variant_data(item, ident.name, sd, gen)),
476             hir::ItemKind::Union(ref sd, ref gen) =>
477                 om.unions.push(self.visit_union_data(item, ident.name, sd, gen)),
478             hir::ItemKind::Fn(ref fd, header, ref gen, body) =>
479                 self.visit_fn(om, item, ident.name, &**fd, header, gen, body),
480             hir::ItemKind::Ty(ref ty, ref gen) => {
481                 let t = Typedef {
482                     ty: ty.clone(),
483                     gen: gen.clone(),
484                     name: ident.name,
485                     id: item.hir_id,
486                     attrs: item.attrs.clone(),
487                     whence: item.span,
488                     vis: item.vis.clone(),
489                     stab: self.stability(item.hir_id),
490                     depr: self.deprecation(item.hir_id),
491                 };
492                 om.typedefs.push(t);
493             },
494             hir::ItemKind::Existential(ref exist_ty) => {
495                 let t = Existential {
496                     exist_ty: exist_ty.clone(),
497                     name: ident.name,
498                     id: item.hir_id,
499                     attrs: item.attrs.clone(),
500                     whence: item.span,
501                     vis: item.vis.clone(),
502                     stab: self.stability(item.hir_id),
503                     depr: self.deprecation(item.hir_id),
504                 };
505                 om.existentials.push(t);
506             },
507             hir::ItemKind::Static(ref ty, ref mut_, ref exp) => {
508                 let s = Static {
509                     type_: ty.clone(),
510                     mutability: mut_.clone(),
511                     expr: exp.clone(),
512                     id: item.hir_id,
513                     name: ident.name,
514                     attrs: item.attrs.clone(),
515                     whence: item.span,
516                     vis: item.vis.clone(),
517                     stab: self.stability(item.hir_id),
518                     depr: self.deprecation(item.hir_id),
519                 };
520                 om.statics.push(s);
521             },
522             hir::ItemKind::Const(ref ty, ref exp) => {
523                 let s = Constant {
524                     type_: ty.clone(),
525                     expr: exp.clone(),
526                     id: item.hir_id,
527                     name: ident.name,
528                     attrs: item.attrs.clone(),
529                     whence: item.span,
530                     vis: item.vis.clone(),
531                     stab: self.stability(item.hir_id),
532                     depr: self.deprecation(item.hir_id),
533                 };
534                 om.constants.push(s);
535             },
536             hir::ItemKind::Trait(is_auto, unsafety, ref gen, ref b, ref item_ids) => {
537                 let items = item_ids.iter()
538                                     .map(|ti| self.cx.tcx.hir().trait_item(ti.id).clone())
539                                     .collect();
540                 let t = Trait {
541                     is_auto,
542                     unsafety,
543                     name: ident.name,
544                     items,
545                     generics: gen.clone(),
546                     bounds: b.iter().cloned().collect(),
547                     id: item.hir_id,
548                     attrs: item.attrs.clone(),
549                     whence: item.span,
550                     vis: item.vis.clone(),
551                     stab: self.stability(item.hir_id),
552                     depr: self.deprecation(item.hir_id),
553                 };
554                 om.traits.push(t);
555             },
556             hir::ItemKind::TraitAlias(ref gen, ref b) => {
557                 let t = TraitAlias {
558                     name: ident.name,
559                     generics: gen.clone(),
560                     bounds: b.iter().cloned().collect(),
561                     id: item.hir_id,
562                     attrs: item.attrs.clone(),
563                     whence: item.span,
564                     vis: item.vis.clone(),
565                     stab: self.stability(item.hir_id),
566                     depr: self.deprecation(item.hir_id),
567                 };
568                 om.trait_aliases.push(t);
569             },
570
571             hir::ItemKind::Impl(unsafety,
572                           polarity,
573                           defaultness,
574                           ref gen,
575                           ref tr,
576                           ref ty,
577                           ref item_ids) => {
578                 // Don't duplicate impls when inlining or if it's implementing a trait, we'll pick
579                 // them up regardless of where they're located.
580                 if !self.inlining && tr.is_none() {
581                     let items = item_ids.iter()
582                                         .map(|ii| self.cx.tcx.hir().impl_item(ii.id).clone())
583                                         .collect();
584                     let i = Impl {
585                         unsafety,
586                         polarity,
587                         defaultness,
588                         generics: gen.clone(),
589                         trait_: tr.clone(),
590                         for_: ty.clone(),
591                         items,
592                         attrs: item.attrs.clone(),
593                         id: item.hir_id,
594                         whence: item.span,
595                         vis: item.vis.clone(),
596                         stab: self.stability(item.hir_id),
597                         depr: self.deprecation(item.hir_id),
598                     };
599                     om.impls.push(i);
600                 }
601             },
602         }
603     }
604
605     // Convert each `exported_macro` into a doc item.
606     fn visit_local_macro(
607         &self,
608         def: &hir::MacroDef,
609         renamed: Option<ast::Name>
610     ) -> Macro {
611         debug!("visit_local_macro: {}", def.name);
612         let tts = def.body.trees().collect::<Vec<_>>();
613         // Extract the spans of all matchers. They represent the "interface" of the macro.
614         let matchers = tts.chunks(4).map(|arm| arm[0].span()).collect();
615
616         Macro {
617
618             def_id: self.cx.tcx.hir().local_def_id_from_hir_id(def.hir_id),
619             attrs: def.attrs.clone(),
620             name: renamed.unwrap_or(def.name),
621             whence: def.span,
622             matchers,
623             stab: self.stability(def.hir_id),
624             depr: self.deprecation(def.hir_id),
625             imported_from: None,
626         }
627     }
628 }