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