1 //! The Rust AST Visitor. Extracts useful information and massages it into a form
2 //! usable for `clean`.
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};
11 use syntax::ext::base::MacroKind;
12 use syntax::source_map::Spanned;
13 use syntax_pos::{self, Span};
18 use crate::clean::{self, AttributesExt, NestedAttributesExt, def_id_to_path};
19 use crate::doctree::*;
22 // Looks to me like the first two of these are actually
23 // output parameters, maybe only mutated once; perhaps
24 // better simply to have the visit method return a tuple
27 // Also, is there some reason that this doesn't use the 'visit'
28 // framework from syntax?.
30 pub struct RustdocVisitor<'a, 'tcx> {
32 pub attrs: hir::HirVec<ast::Attribute>,
33 pub cx: &'a core::DocContext<'tcx>,
34 view_item_stack: FxHashSet<hir::HirId>,
36 /// Are the current module and all of its parents public?
37 inside_public_path: bool,
38 exact_paths: Option<FxHashMap<DefId, Vec<String>>>,
41 impl<'a, 'tcx> RustdocVisitor<'a, 'tcx> {
43 cx: &'a core::DocContext<'tcx>
44 ) -> RustdocVisitor<'a, 'tcx> {
45 // If the root is re-exported, terminate all recursion.
46 let mut stack = FxHashSet::default();
47 stack.insert(hir::CRATE_HIR_ID);
49 module: Module::new(None),
50 attrs: hir::HirVec::new(),
52 view_item_stack: stack,
54 inside_public_path: true,
55 exact_paths: Some(FxHashMap::default()),
59 fn store_path(&mut self, did: DefId) {
60 // We can't use the entry API, as that keeps the mutable borrow of `self` active
61 // when we try to use `cx`.
62 let exact_paths = self.exact_paths.as_mut().unwrap();
63 if exact_paths.get(&did).is_none() {
64 let path = def_id_to_path(self.cx, did, self.cx.crate_name.clone());
65 exact_paths.insert(did, path);
69 fn stability(&self, id: hir::HirId) -> Option<attr::Stability> {
70 self.cx.tcx.hir().opt_local_def_id_from_hir_id(id)
71 .and_then(|def_id| self.cx.tcx.lookup_stability(def_id)).cloned()
74 fn deprecation(&self, id: hir::HirId) -> Option<attr::Deprecation> {
75 self.cx.tcx.hir().opt_local_def_id_from_hir_id(id)
76 .and_then(|def_id| self.cx.tcx.lookup_deprecation(def_id))
79 pub fn visit(&mut self, krate: &hir::Crate) {
80 self.attrs = krate.attrs.clone();
82 self.module = self.visit_mod_contents(krate.span,
84 Spanned { span: syntax_pos::DUMMY_SP,
85 node: hir::VisibilityKind::Public },
89 // Attach the crate's exported macros to the top-level module:
90 let macro_exports: Vec<_> =
91 krate.exported_macros.iter().map(|def| self.visit_local_macro(def, None)).collect();
92 self.module.macros.extend(macro_exports);
93 self.module.is_crate = true;
95 self.cx.renderinfo.borrow_mut().exact_paths = self.exact_paths.take().unwrap();
98 pub fn visit_variant_data(&mut self, item: &hir::Item,
99 name: ast::Name, sd: &hir::VariantData,
100 generics: &hir::Generics) -> Struct {
101 debug!("Visiting struct");
102 let struct_type = struct_type_from_def(&*sd);
107 vis: item.vis.clone(),
108 stab: self.stability(item.hir_id),
109 depr: self.deprecation(item.hir_id),
110 attrs: item.attrs.clone(),
111 generics: generics.clone(),
112 fields: sd.fields().iter().cloned().collect(),
117 pub fn visit_union_data(&mut self, item: &hir::Item,
118 name: ast::Name, sd: &hir::VariantData,
119 generics: &hir::Generics) -> Union {
120 debug!("Visiting union");
121 let struct_type = struct_type_from_def(&*sd);
126 vis: item.vis.clone(),
127 stab: self.stability(item.hir_id),
128 depr: self.deprecation(item.hir_id),
129 attrs: item.attrs.clone(),
130 generics: generics.clone(),
131 fields: sd.fields().iter().cloned().collect(),
136 pub fn visit_enum_def(&mut self, it: &hir::Item,
137 name: ast::Name, def: &hir::EnumDef,
138 params: &hir::Generics) -> Enum {
139 debug!("Visiting enum");
142 variants: def.variants.iter().map(|v| Variant {
143 name: v.node.ident.name,
145 attrs: v.node.attrs.clone(),
146 stab: self.stability(v.node.id),
147 depr: self.deprecation(v.node.id),
148 def: v.node.data.clone(),
152 stab: self.stability(it.hir_id),
153 depr: self.deprecation(it.hir_id),
154 generics: params.clone(),
155 attrs: it.attrs.clone(),
161 pub fn visit_fn(&mut self, om: &mut Module, item: &hir::Item,
162 name: ast::Name, fd: &hir::FnDecl,
163 header: hir::FnHeader,
166 debug!("Visiting fn");
167 let macro_kind = item.attrs.iter().filter_map(|a| {
168 if a.check_name("proc_macro") {
169 Some(MacroKind::Bang)
170 } else if a.check_name("proc_macro_derive") {
171 Some(MacroKind::Derive)
172 } else if a.check_name("proc_macro_attribute") {
173 Some(MacroKind::Attr)
180 let name = if kind == MacroKind::Derive {
181 item.attrs.lists("proc_macro_derive")
182 .filter_map(|mi| mi.ident())
184 .expect("proc-macro derives require a name")
190 let mut helpers = Vec::new();
191 for mi in item.attrs.lists("proc_macro_derive") {
192 if !mi.check_name("attributes") {
196 if let Some(list) = mi.meta_item_list() {
197 for inner_mi in list {
198 if let Some(ident) = inner_mi.ident() {
199 helpers.push(ident.name);
205 om.proc_macros.push(ProcMacro {
210 attrs: item.attrs.clone(),
212 stab: self.stability(item.hir_id),
213 depr: self.deprecation(item.hir_id),
217 om.fns.push(Function {
219 vis: item.vis.clone(),
220 stab: self.stability(item.hir_id),
221 depr: self.deprecation(item.hir_id),
222 attrs: item.attrs.clone(),
226 generics: gen.clone(),
234 pub fn visit_mod_contents(&mut self, span: Span, attrs: hir::HirVec<ast::Attribute>,
235 vis: hir::Visibility, id: hir::HirId,
237 name: Option<ast::Name>) -> Module {
238 let mut om = Module::new(name);
239 om.where_outer = span;
240 om.where_inner = m.inner;
242 om.vis = vis.clone();
243 om.stab = self.stability(id);
244 om.depr = self.deprecation(id);
245 om.id = self.cx.tcx.hir().hir_to_node_id(id);
246 // Keep track of if there were any private modules in the path.
247 let orig_inside_public_path = self.inside_public_path;
248 self.inside_public_path &= vis.node.is_pub();
249 for i in &m.item_ids {
250 let item = self.cx.tcx.hir().expect_item_by_hir_id(i.id);
251 self.visit_item(item, None, &mut om);
253 self.inside_public_path = orig_inside_public_path;
257 /// Tries to resolve the target of a `pub use` statement and inlines the
258 /// target if it is defined locally and would not be documented otherwise,
259 /// or when it is specifically requested with `please_inline`.
260 /// (the latter is the case when the import is marked `doc(inline)`)
262 /// Cross-crate inlining occurs later on during crate cleaning
263 /// and follows different rules.
265 /// Returns `true` if the target has been inlined.
266 fn maybe_inline_local(&mut self,
269 renamed: Option<ast::Ident>,
272 please_inline: bool) -> bool {
274 fn inherits_doc_hidden(cx: &core::DocContext<'_>, mut node: hir::HirId) -> bool {
275 while let Some(id) = cx.tcx.hir().get_enclosing_scope(node) {
277 if cx.tcx.hir().attrs_by_hir_id(node).lists("doc").has_word("hidden") {
280 if node == hir::CRATE_HIR_ID {
287 debug!("maybe_inline_local res: {:?}", res);
289 let tcx = self.cx.tcx;
290 let res_did = if let Some(did) = res.opt_def_id() {
296 let use_attrs = tcx.hir().attrs_by_hir_id(id);
297 // Don't inline `doc(hidden)` imports so they can be stripped at a later stage.
298 let is_no_inline = use_attrs.lists("doc").has_word("no_inline") ||
299 use_attrs.lists("doc").has_word("hidden");
301 // For cross-crate impl inlining we need to know whether items are
302 // reachable in documentation -- a previously nonreachable item can be
303 // made reachable by cross-crate inlining which we're checking here.
304 // (this is done here because we need to know this upfront).
305 if !res_did.is_local() && !is_no_inline {
306 let attrs = clean::inline::load_attrs(self.cx, res_did);
307 let self_is_hidden = attrs.lists("doc").has_word("hidden");
309 Res::Def(DefKind::Trait, did) |
310 Res::Def(DefKind::Struct, did) |
311 Res::Def(DefKind::Union, did) |
312 Res::Def(DefKind::Enum, did) |
313 Res::Def(DefKind::ForeignTy, did) |
314 Res::Def(DefKind::TyAlias, did) if !self_is_hidden => {
318 .insert(did, AccessLevel::Public);
320 Res::Def(DefKind::Mod, did) => if !self_is_hidden {
321 crate::visit_lib::LibEmbargoVisitor::new(self.cx).visit_mod(did);
329 let res_hir_id = match tcx.hir().as_local_hir_id(res_did) {
330 Some(n) => n, None => return false
333 let is_private = !self.cx.renderinfo.borrow().access_levels.is_public(res_did);
334 let is_hidden = inherits_doc_hidden(self.cx, res_hir_id);
336 // Only inline if requested or if the item would otherwise be stripped.
337 if (!please_inline && !is_private && !is_hidden) || is_no_inline {
341 if !self.view_item_stack.insert(res_hir_id) { return false }
343 let ret = match tcx.hir().get_by_hir_id(res_hir_id) {
344 Node::Item(&hir::Item { node: hir::ItemKind::Mod(ref m), .. }) if glob => {
345 let prev = mem::replace(&mut self.inlining, true);
346 for i in &m.item_ids {
347 let i = self.cx.tcx.hir().expect_item_by_hir_id(i.id);
348 self.visit_item(i, None, om);
350 self.inlining = prev;
353 Node::Item(it) if !glob => {
354 let prev = mem::replace(&mut self.inlining, true);
355 self.visit_item(it, renamed, om);
356 self.inlining = prev;
359 Node::ForeignItem(it) if !glob => {
360 // Generate a fresh `extern {}` block if we want to inline a foreign item.
361 om.foreigns.push(hir::ForeignMod {
362 abi: tcx.hir().get_foreign_abi_by_hir_id(it.hir_id),
363 items: vec![hir::ForeignItem {
364 ident: renamed.unwrap_or(it.ident),
370 Node::MacroDef(def) if !glob => {
371 om.macros.push(self.visit_local_macro(def, renamed.map(|i| i.name)));
376 self.view_item_stack.remove(&res_hir_id);
380 pub fn visit_item(&mut self, item: &hir::Item,
381 renamed: Option<ast::Ident>, om: &mut Module) {
382 debug!("Visiting item {:?}", item);
383 let ident = renamed.unwrap_or(item.ident);
385 if item.vis.node.is_pub() {
386 let def_id = self.cx.tcx.hir().local_def_id_from_hir_id(item.hir_id);
387 self.store_path(def_id);
391 hir::ItemKind::ForeignMod(ref fm) => {
392 // If inlining we only want to include public functions.
393 om.foreigns.push(if self.inlining {
396 items: fm.items.iter().filter(|i| i.vis.node.is_pub()).cloned().collect(),
402 // If we're inlining, skip private items.
403 _ if self.inlining && !item.vis.node.is_pub() => {}
404 hir::ItemKind::GlobalAsm(..) => {}
405 hir::ItemKind::ExternCrate(orig_name) => {
406 let def_id = self.cx.tcx.hir().local_def_id_from_hir_id(item.hir_id);
407 om.extern_crates.push(ExternCrate {
408 cnum: self.cx.tcx.extern_mod_stmt_cnum(def_id)
409 .unwrap_or(LOCAL_CRATE),
411 path: orig_name.map(|x|x.to_string()),
412 vis: item.vis.clone(),
413 attrs: item.attrs.clone(),
417 hir::ItemKind::Use(_, hir::UseKind::ListStem) => {}
418 hir::ItemKind::Use(ref path, kind) => {
419 let is_glob = kind == hir::UseKind::Glob;
421 // Struct and variant constructors and proc macro stubs always show up alongside
422 // their definitions, we've already processed them so just discard these.
424 Res::Def(DefKind::Ctor(..), _)
426 | Res::Def(DefKind::Macro(MacroKind::ProcMacroStub), _) => return,
430 // If there was a private module in the current path then don't bother inlining
431 // anything as it will probably be stripped anyway.
432 if item.vis.node.is_pub() && self.inside_public_path {
433 let please_inline = item.attrs.iter().any(|item| {
434 match item.meta_item_list() {
435 Some(ref list) if item.check_name("doc") => {
436 list.iter().any(|i| i.check_name("inline"))
441 let ident = if is_glob { None } else { Some(ident) };
442 if self.maybe_inline_local(item.hir_id,
452 om.imports.push(Import {
455 vis: item.vis.clone(),
456 attrs: item.attrs.clone(),
457 path: (**path).clone(),
462 hir::ItemKind::Mod(ref m) => {
463 om.mods.push(self.visit_mod_contents(item.span,
470 hir::ItemKind::Enum(ref ed, ref gen) =>
471 om.enums.push(self.visit_enum_def(item, ident.name, ed, gen)),
472 hir::ItemKind::Struct(ref sd, ref gen) =>
473 om.structs.push(self.visit_variant_data(item, ident.name, sd, gen)),
474 hir::ItemKind::Union(ref sd, ref gen) =>
475 om.unions.push(self.visit_union_data(item, ident.name, sd, gen)),
476 hir::ItemKind::Fn(ref fd, header, ref gen, body) =>
477 self.visit_fn(om, item, ident.name, &**fd, header, gen, body),
478 hir::ItemKind::Ty(ref ty, ref gen) => {
484 attrs: item.attrs.clone(),
486 vis: item.vis.clone(),
487 stab: self.stability(item.hir_id),
488 depr: self.deprecation(item.hir_id),
492 hir::ItemKind::Existential(ref exist_ty) => {
493 let t = Existential {
494 exist_ty: exist_ty.clone(),
497 attrs: item.attrs.clone(),
499 vis: item.vis.clone(),
500 stab: self.stability(item.hir_id),
501 depr: self.deprecation(item.hir_id),
503 om.existentials.push(t);
505 hir::ItemKind::Static(ref ty, ref mut_, ref exp) => {
508 mutability: mut_.clone(),
512 attrs: item.attrs.clone(),
514 vis: item.vis.clone(),
515 stab: self.stability(item.hir_id),
516 depr: self.deprecation(item.hir_id),
520 hir::ItemKind::Const(ref ty, ref exp) => {
526 attrs: item.attrs.clone(),
528 vis: item.vis.clone(),
529 stab: self.stability(item.hir_id),
530 depr: self.deprecation(item.hir_id),
532 om.constants.push(s);
534 hir::ItemKind::Trait(is_auto, unsafety, ref gen, ref b, ref item_ids) => {
535 let items = item_ids.iter()
536 .map(|ti| self.cx.tcx.hir().trait_item(ti.id).clone())
543 generics: gen.clone(),
544 bounds: b.iter().cloned().collect(),
546 attrs: item.attrs.clone(),
548 vis: item.vis.clone(),
549 stab: self.stability(item.hir_id),
550 depr: self.deprecation(item.hir_id),
554 hir::ItemKind::TraitAlias(ref gen, ref b) => {
557 generics: gen.clone(),
558 bounds: b.iter().cloned().collect(),
560 attrs: item.attrs.clone(),
562 vis: item.vis.clone(),
563 stab: self.stability(item.hir_id),
564 depr: self.deprecation(item.hir_id),
566 om.trait_aliases.push(t);
569 hir::ItemKind::Impl(unsafety,
576 // Don't duplicate impls when inlining or if it's implementing a trait, we'll pick
577 // them up regardless of where they're located.
578 if !self.inlining && tr.is_none() {
579 let items = item_ids.iter()
580 .map(|ii| self.cx.tcx.hir().impl_item(ii.id).clone())
586 generics: gen.clone(),
590 attrs: item.attrs.clone(),
593 vis: item.vis.clone(),
594 stab: self.stability(item.hir_id),
595 depr: self.deprecation(item.hir_id),
603 // Convert each `exported_macro` into a doc item.
604 fn visit_local_macro(
607 renamed: Option<ast::Name>
609 debug!("visit_local_macro: {}", def.name);
610 let tts = def.body.trees().collect::<Vec<_>>();
611 // Extract the spans of all matchers. They represent the "interface" of the macro.
612 let matchers = tts.chunks(4).map(|arm| arm[0].span()).collect();
616 def_id: self.cx.tcx.hir().local_def_id_from_hir_id(def.hir_id),
617 attrs: def.attrs.clone(),
618 name: renamed.unwrap_or(def.name),
621 stab: self.stability(def.hir_id),
622 depr: self.deprecation(def.hir_id),