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