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<hir::HirId>,
  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(hir::CRATE_HIR_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                 id: v.node.id,
 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(),
 149                 whence: v.span,
 150             }).collect(),
 151             vis: it.vis.clone(),
 152             stab: self.stability(it.hir_id),
 153             depr: self.deprecation(it.hir_id),
 154             generics: params.clone(),
 155             attrs: it.attrs.clone(),
 156             id: it.hir_id,
 157             whence: it.span,
 158         }
 159     }
 160
 161     pub fn visit_fn(&mut self, om: &mut Module, item: &hir::Item,
 162                     name: ast::Name, fd: &hir::FnDecl,
 163                     header: hir::FnHeader,
 164                     gen: &hir::Generics,
 165                     body: hir::BodyId) {
 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)
 174             } else {
 175                 None
 176             }
 177         }).next();
 178         match macro_kind {
 179             Some(kind) => {
 180                 let name = if kind == MacroKind::Derive {
 181                     item.attrs.lists("proc_macro_derive")
 182                               .filter_map(|mi| mi.ident())
 183                               .next()
 184                               .expect("proc-macro derives require a name")
 185                               .name
 186                 } else {
 187                     name
 188                 };
 189
 190                 let mut helpers = Vec::new();
 191                 for mi in item.attrs.lists("proc_macro_derive") {
 192                     if !mi.check_name("attributes") {
 193                         continue;
 194                     }
 195
 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);
 200                             }
 201                         }
 202                     }
 203                 }
 204
 205                 om.proc_macros.push(ProcMacro {
 206                     name,
 207                     id: item.hir_id,
 208                     kind,
 209                     helpers,
 210                     attrs: item.attrs.clone(),
 211                     whence: item.span,
 212                     stab: self.stability(item.hir_id),
 213                     depr: self.deprecation(item.hir_id),
 214                 });
 215             }
 216             None => {
 217                 om.fns.push(Function {
 218                     id: item.hir_id,
 219                     vis: item.vis.clone(),
 220                     stab: self.stability(item.hir_id),
 221                     depr: self.deprecation(item.hir_id),
 222                     attrs: item.attrs.clone(),
 223                     decl: fd.clone(),
 224                     name,
 225                     whence: item.span,
 226                     generics: gen.clone(),
 227                     header,
 228                     body,
 229                 });
 230             }
 231         }
 232     }
 233
 234     pub fn visit_mod_contents(&mut self, span: Span, attrs: hir::HirVec<ast::Attribute>,
 235                               vis: hir::Visibility, id: hir::HirId,
 236                               m: &hir::Mod,
 237                               name: Option<ast::Name>) -> Module {
 238         let mut om = Module::new(name);
 239         om.where_outer = span;
 240         om.where_inner = m.inner;
 241         om.attrs = attrs;
 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);
 252         }
 253         self.inside_public_path = orig_inside_public_path;
 254         om
 255     }
 256
 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)`)
 261     ///
 262     /// Cross-crate inlining occurs later on during crate cleaning
 263     /// and follows different rules.
 264     ///
 265     /// Returns `true` if the target has been inlined.
 266     fn maybe_inline_local(&mut self,
 267                           id: hir::HirId,
 268                           def: Def,
 269                           renamed: Option<ast::Ident>,
 270                           glob: bool,
 271                           om: &mut Module,
 272                           please_inline: bool) -> bool {
 273
 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) {
 276                 node = id;
 277                 if cx.tcx.hir().attrs_by_hir_id(node).lists("doc").has_word("hidden") {
 278                     return true;
 279                 }
 280                 if node == hir::CRATE_HIR_ID {
 281                     break;
 282                 }
 283             }
 284             false
 285         }
 286
 287         debug!("maybe_inline_local def: {:?}", def);
 288
 289         let tcx = self.cx.tcx;
 290         let def_did = if let Some(did) = def.opt_def_id() {
 291             did
 292         } else {
 293             return false;
 294         };
 295
 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");
 300
 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 !def_did.is_local() && !is_no_inline {
 306             let attrs = clean::inline::load_attrs(self.cx, def_did);
 307             let self_is_hidden = attrs.lists("doc").has_word("hidden");
 308             match def {
 309                 Def::Trait(did) |
 310                 Def::Struct(did) |
 311                 Def::Union(did) |
 312                 Def::Enum(did) |
 313                 Def::ForeignTy(did) |
 314                 Def::TyAlias(did) if !self_is_hidden => {
 315                     self.cx.renderinfo
 316                         .borrow_mut()
 317                         .access_levels.map
 318                         .insert(did, AccessLevel::Public);
 319                 },
 320                 Def::Mod(did) => if !self_is_hidden {
 321                     crate::visit_lib::LibEmbargoVisitor::new(self.cx).visit_mod(did);
 322                 },
 323                 _ => {},
 324             }
 325
 326             return false
 327         }
 328
 329         let def_hir_id = match tcx.hir().as_local_hir_id(def_did) {
 330             Some(n) => n, None => return false
 331         };
 332
 333         let is_private = !self.cx.renderinfo.borrow().access_levels.is_public(def_did);
 334         let is_hidden = inherits_doc_hidden(self.cx, def_hir_id);
 335
 336         // Only inline if requested or if the item would otherwise be stripped.
 337         if (!please_inline && !is_private && !is_hidden) || is_no_inline {
 338             return false
 339         }
 340
 341         if !self.view_item_stack.insert(def_hir_id) { return false }
 342
 343         let ret = match tcx.hir().get_by_hir_id(def_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);
 349                 }
 350                 self.inlining = prev;
 351                 true
 352             }
 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;
 357                 true
 358             }
 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),
 365                         .. it.clone()
 366                     }].into(),
 367                 });
 368                 true
 369             }
 370             Node::MacroDef(def) if !glob => {
 371                 om.macros.push(self.visit_local_macro(def, renamed.map(|i| i.name)));
 372                 true
 373             }
 374             _ => false,
 375         };
 376         self.view_item_stack.remove(&def_hir_id);
 377         ret
 378     }
 379
 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);
 384
 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);
 388         }
 389
 390         match item.node {
 391             hir::ItemKind::ForeignMod(ref fm) => {
 392                 // If inlining we only want to include public functions.
 393                 om.foreigns.push(if self.inlining {
 394                     hir::ForeignMod {
 395                         abi: fm.abi,
 396                         items: fm.items.iter().filter(|i| i.vis.node.is_pub()).cloned().collect(),
 397                     }
 398                 } else {
 399                     fm.clone()
 400                 });
 401             }
 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),
 410                     name: ident.name,
 411                     path: orig_name.map(|x|x.to_string()),
 412                     vis: item.vis.clone(),
 413                     attrs: item.attrs.clone(),
 414                     whence: item.span,
 415                 })
 416             }
 417             hir::ItemKind::Use(_, hir::UseKind::ListStem) => {}
 418             hir::ItemKind::Use(ref path, kind) => {
 419                 let is_glob = kind == hir::UseKind::Glob;
 420
 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.
 423                 match path.def {
 424                     Def::Ctor(..) | Def::SelfCtor(..) | Def::Macro(_, MacroKind::ProcMacroStub) =>
 425                         return,
 426                     _ => {}
 427                 }
 428
 429                 // If there was a private module in the current path then don't bother inlining
 430                 // anything as it will probably be stripped anyway.
 431                 if item.vis.node.is_pub() && self.inside_public_path {
 432                     let please_inline = item.attrs.iter().any(|item| {
 433                         match item.meta_item_list() {
 434                             Some(ref list) if item.check_name("doc") => {
 435                                 list.iter().any(|i| i.check_name("inline"))
 436                             }
 437                             _ => false,
 438                         }
 439                     });
 440                     let ident = if is_glob { None } else { Some(ident) };
 441                     if self.maybe_inline_local(item.hir_id,
 442                                                path.def,
 443                                                ident,
 444                                                is_glob,
 445                                                om,
 446                                                please_inline) {
 447                         return;
 448                     }
 449                 }
 450
 451                 om.imports.push(Import {
 452                     name: ident.name,
 453                     id: item.hir_id,
 454                     vis: item.vis.clone(),
 455                     attrs: item.attrs.clone(),
 456                     path: (**path).clone(),
 457                     glob: is_glob,
 458                     whence: item.span,
 459                 });
 460             }
 461             hir::ItemKind::Mod(ref m) => {
 462                 om.mods.push(self.visit_mod_contents(item.span,
 463                                                      item.attrs.clone(),
 464                                                      item.vis.clone(),
 465                                                      item.hir_id,
 466                                                      m,
 467                                                      Some(ident.name)));
 468             },
 469             hir::ItemKind::Enum(ref ed, ref gen) =>
 470                 om.enums.push(self.visit_enum_def(item, ident.name, ed, gen)),
 471             hir::ItemKind::Struct(ref sd, ref gen) =>
 472                 om.structs.push(self.visit_variant_data(item, ident.name, sd, gen)),
 473             hir::ItemKind::Union(ref sd, ref gen) =>
 474                 om.unions.push(self.visit_union_data(item, ident.name, sd, gen)),
 475             hir::ItemKind::Fn(ref fd, header, ref gen, body) =>
 476                 self.visit_fn(om, item, ident.name, &**fd, header, gen, body),
 477             hir::ItemKind::Ty(ref ty, ref gen) => {
 478                 let t = Typedef {
 479                     ty: ty.clone(),
 480                     gen: gen.clone(),
 481                     name: ident.name,
 482                     id: item.hir_id,
 483                     attrs: item.attrs.clone(),
 484                     whence: item.span,
 485                     vis: item.vis.clone(),
 486                     stab: self.stability(item.hir_id),
 487                     depr: self.deprecation(item.hir_id),
 488                 };
 489                 om.typedefs.push(t);
 490             },
 491             hir::ItemKind::Existential(ref exist_ty) => {
 492                 let t = Existential {
 493                     exist_ty: exist_ty.clone(),
 494                     name: ident.name,
 495                     id: item.hir_id,
 496                     attrs: item.attrs.clone(),
 497                     whence: item.span,
 498                     vis: item.vis.clone(),
 499                     stab: self.stability(item.hir_id),
 500                     depr: self.deprecation(item.hir_id),
 501                 };
 502                 om.existentials.push(t);
 503             },
 504             hir::ItemKind::Static(ref ty, ref mut_, ref exp) => {
 505                 let s = Static {
 506                     type_: ty.clone(),
 507                     mutability: mut_.clone(),
 508                     expr: exp.clone(),
 509                     id: item.hir_id,
 510                     name: ident.name,
 511                     attrs: item.attrs.clone(),
 512                     whence: item.span,
 513                     vis: item.vis.clone(),
 514                     stab: self.stability(item.hir_id),
 515                     depr: self.deprecation(item.hir_id),
 516                 };
 517                 om.statics.push(s);
 518             },
 519             hir::ItemKind::Const(ref ty, ref exp) => {
 520                 let s = Constant {
 521                     type_: ty.clone(),
 522                     expr: exp.clone(),
 523                     id: item.hir_id,
 524                     name: ident.name,
 525                     attrs: item.attrs.clone(),
 526                     whence: item.span,
 527                     vis: item.vis.clone(),
 528                     stab: self.stability(item.hir_id),
 529                     depr: self.deprecation(item.hir_id),
 530                 };
 531                 om.constants.push(s);
 532             },
 533             hir::ItemKind::Trait(is_auto, unsafety, ref gen, ref b, ref item_ids) => {
 534                 let items = item_ids.iter()
 535                                     .map(|ti| self.cx.tcx.hir().trait_item(ti.id).clone())
 536                                     .collect();
 537                 let t = Trait {
 538                     is_auto,
 539                     unsafety,
 540                     name: ident.name,
 541                     items,
 542                     generics: gen.clone(),
 543                     bounds: b.iter().cloned().collect(),
 544                     id: item.hir_id,
 545                     attrs: item.attrs.clone(),
 546                     whence: item.span,
 547                     vis: item.vis.clone(),
 548                     stab: self.stability(item.hir_id),
 549                     depr: self.deprecation(item.hir_id),
 550                 };
 551                 om.traits.push(t);
 552             },
 553             hir::ItemKind::TraitAlias(ref gen, ref b) => {
 554                 let t = TraitAlias {
 555                     name: ident.name,
 556                     generics: gen.clone(),
 557                     bounds: b.iter().cloned().collect(),
 558                     id: item.hir_id,
 559                     attrs: item.attrs.clone(),
 560                     whence: item.span,
 561                     vis: item.vis.clone(),
 562                     stab: self.stability(item.hir_id),
 563                     depr: self.deprecation(item.hir_id),
 564                 };
 565                 om.trait_aliases.push(t);
 566             },
 567
 568             hir::ItemKind::Impl(unsafety,
 569                           polarity,
 570                           defaultness,
 571                           ref gen,
 572                           ref tr,
 573                           ref ty,
 574                           ref item_ids) => {
 575                 // Don't duplicate impls when inlining or if it's implementing a trait, we'll pick
 576                 // them up regardless of where they're located.
 577                 if !self.inlining && tr.is_none() {
 578                     let items = item_ids.iter()
 579                                         .map(|ii| self.cx.tcx.hir().impl_item(ii.id).clone())
 580                                         .collect();
 581                     let i = Impl {
 582                         unsafety,
 583                         polarity,
 584                         defaultness,
 585                         generics: gen.clone(),
 586                         trait_: tr.clone(),
 587                         for_: ty.clone(),
 588                         items,
 589                         attrs: item.attrs.clone(),
 590                         id: item.hir_id,
 591                         whence: item.span,
 592                         vis: item.vis.clone(),
 593                         stab: self.stability(item.hir_id),
 594                         depr: self.deprecation(item.hir_id),
 595                     };
 596                     om.impls.push(i);
 597                 }
 598             },
 599         }
 600     }
 601
 602     // Convert each `exported_macro` into a doc item.
 603     fn visit_local_macro(
 604         &self,
 605         def: &hir::MacroDef,
 606         renamed: Option<ast::Name>
 607     ) -> Macro {
 608         debug!("visit_local_macro: {}", def.name);
 609         let tts = def.body.trees().collect::<Vec<_>>();
 610         // Extract the spans of all matchers. They represent the "interface" of the macro.
 611         let matchers = tts.chunks(4).map(|arm| arm[0].span()).collect();
 612
 613         Macro {
 614
 615             def_id: self.cx.tcx.hir().local_def_id_from_hir_id(def.hir_id),
 616             attrs: def.attrs.clone(),
 617             name: renamed.unwrap_or(def.name),
 618             whence: def.span,
 619             matchers,
 620             stab: self.stability(def.hir_id),
 621             depr: self.deprecation(def.hir_id),
 622             imported_from: None,
 623         }
 624     }
 625 }