"Fossies" - the Fresh Open Source Software Archive

Member "rustc-1.60.0-src/src/librustdoc/visit_ast.rs" (4 Apr 2022, 15306 Bytes) of package /linux/misc/rustc-1.60.0-src.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Rust source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "visit_ast.rs": 1.59.0_vs_1.60.0.

    1 //! The Rust AST Visitor. Extracts useful information and massages it into a form
    2 //! usable for `clean`.
    3 
    4 use rustc_data_structures::fx::{FxHashMap, FxHashSet};
    5 use rustc_hir as hir;
    6 use rustc_hir::def::{DefKind, Res};
    7 use rustc_hir::def_id::DefId;
    8 use rustc_hir::Node;
    9 use rustc_hir::CRATE_HIR_ID;
   10 use rustc_middle::middle::privacy::AccessLevel;
   11 use rustc_middle::ty::TyCtxt;
   12 use rustc_span::def_id::{CRATE_DEF_ID, LOCAL_CRATE};
   13 use rustc_span::symbol::{kw, sym, Symbol};
   14 use rustc_span::Span;
   15 
   16 use std::mem;
   17 
   18 use crate::clean::{self, cfg::Cfg, AttributesExt, NestedAttributesExt};
   19 use crate::core;
   20 
   21 /// This module is used to store stuff from Rust's AST in a more convenient
   22 /// manner (and with prettier names) before cleaning.
   23 #[derive(Debug)]
   24 crate struct Module<'hir> {
   25     crate name: Symbol,
   26     crate where_inner: Span,
   27     crate mods: Vec<Module<'hir>>,
   28     crate id: hir::HirId,
   29     // (item, renamed)
   30     crate items: Vec<(&'hir hir::Item<'hir>, Option<Symbol>)>,
   31     crate foreigns: Vec<(&'hir hir::ForeignItem<'hir>, Option<Symbol>)>,
   32 }
   33 
   34 impl Module<'_> {
   35     crate fn new(name: Symbol, id: hir::HirId, where_inner: Span) -> Self {
   36         Module { name, id, where_inner, mods: Vec::new(), items: Vec::new(), foreigns: Vec::new() }
   37     }
   38 
   39     crate fn where_outer(&self, tcx: TyCtxt<'_>) -> Span {
   40         tcx.hir().span(self.id)
   41     }
   42 }
   43 
   44 // FIXME: Should this be replaced with tcx.def_path_str?
   45 fn def_id_to_path(tcx: TyCtxt<'_>, did: DefId) -> Vec<Symbol> {
   46     let crate_name = tcx.crate_name(did.krate);
   47     let relative = tcx.def_path(did).data.into_iter().filter_map(|elem| elem.data.get_opt_name());
   48     std::iter::once(crate_name).chain(relative).collect()
   49 }
   50 
   51 crate fn inherits_doc_hidden(tcx: TyCtxt<'_>, mut node: hir::HirId) -> bool {
   52     while let Some(id) = tcx.hir().get_enclosing_scope(node) {
   53         node = id;
   54         if tcx.hir().attrs(node).lists(sym::doc).has_word(sym::hidden) {
   55             return true;
   56         }
   57     }
   58     false
   59 }
   60 
   61 // Also, is there some reason that this doesn't use the 'visit'
   62 // framework from syntax?.
   63 
   64 crate struct RustdocVisitor<'a, 'tcx> {
   65     cx: &'a mut core::DocContext<'tcx>,
   66     view_item_stack: FxHashSet<hir::HirId>,
   67     inlining: bool,
   68     /// Are the current module and all of its parents public?
   69     inside_public_path: bool,
   70     exact_paths: FxHashMap<DefId, Vec<Symbol>>,
   71 }
   72 
   73 impl<'a, 'tcx> RustdocVisitor<'a, 'tcx> {
   74     crate fn new(cx: &'a mut core::DocContext<'tcx>) -> RustdocVisitor<'a, 'tcx> {
   75         // If the root is re-exported, terminate all recursion.
   76         let mut stack = FxHashSet::default();
   77         stack.insert(hir::CRATE_HIR_ID);
   78         RustdocVisitor {
   79             cx,
   80             view_item_stack: stack,
   81             inlining: false,
   82             inside_public_path: true,
   83             exact_paths: FxHashMap::default(),
   84         }
   85     }
   86 
   87     fn store_path(&mut self, did: DefId) {
   88         let tcx = self.cx.tcx;
   89         self.exact_paths.entry(did).or_insert_with(|| def_id_to_path(tcx, did));
   90     }
   91 
   92     crate fn visit(mut self) -> Module<'tcx> {
   93         let mut top_level_module = self.visit_mod_contents(
   94             hir::CRATE_HIR_ID,
   95             self.cx.tcx.hir().root_module(),
   96             self.cx.tcx.crate_name(LOCAL_CRATE),
   97         );
   98 
   99         // `#[macro_export] macro_rules!` items are reexported at the top level of the
  100         // crate, regardless of where they're defined. We want to document the
  101         // top level rexport of the macro, not its original definition, since
  102         // the rexport defines the path that a user will actually see. Accordingly,
  103         // we add the rexport as an item here, and then skip over the original
  104         // definition in `visit_item()` below.
  105         //
  106         // We also skip `#[macro_export] macro_rules!` that have already been inserted,
  107         // it can happen if within the same module a `#[macro_export] macro_rules!`
  108         // is declared but also a reexport of itself producing two exports of the same
  109         // macro in the same module.
  110         let mut inserted = FxHashSet::default();
  111         for export in self.cx.tcx.module_reexports(CRATE_DEF_ID).unwrap_or(&[]) {
  112             if let Res::Def(DefKind::Macro(_), def_id) = export.res {
  113                 if let Some(local_def_id) = def_id.as_local() {
  114                     if self.cx.tcx.has_attr(def_id, sym::macro_export) {
  115                         if inserted.insert(def_id) {
  116                             let item = self.cx.tcx.hir().expect_item(local_def_id);
  117                             top_level_module.items.push((item, None));
  118                         }
  119                     }
  120                 }
  121             }
  122         }
  123 
  124         self.cx.cache.hidden_cfg = self
  125             .cx
  126             .tcx
  127             .hir()
  128             .attrs(CRATE_HIR_ID)
  129             .iter()
  130             .filter(|attr| attr.has_name(sym::doc))
  131             .flat_map(|attr| attr.meta_item_list().into_iter().flatten())
  132             .filter(|attr| attr.has_name(sym::cfg_hide))
  133             .flat_map(|attr| {
  134                 attr.meta_item_list()
  135                     .unwrap_or(&[])
  136                     .iter()
  137                     .filter_map(|attr| {
  138                         Cfg::parse(attr.meta_item()?)
  139                             .map_err(|e| self.cx.sess().diagnostic().span_err(e.span, e.msg))
  140                             .ok()
  141                     })
  142                     .collect::<Vec<_>>()
  143             })
  144             .chain([Cfg::Cfg(sym::test, None)].into_iter())
  145             .collect();
  146 
  147         self.cx.cache.exact_paths = self.exact_paths;
  148         top_level_module
  149     }
  150 
  151     fn visit_mod_contents(
  152         &mut self,
  153         id: hir::HirId,
  154         m: &'tcx hir::Mod<'tcx>,
  155         name: Symbol,
  156     ) -> Module<'tcx> {
  157         let mut om = Module::new(name, id, m.inner);
  158         let def_id = self.cx.tcx.hir().local_def_id(id).to_def_id();
  159         // Keep track of if there were any private modules in the path.
  160         let orig_inside_public_path = self.inside_public_path;
  161         self.inside_public_path &= self.cx.tcx.visibility(def_id).is_public();
  162         for &i in m.item_ids {
  163             let item = self.cx.tcx.hir().item(i);
  164             self.visit_item(item, None, &mut om);
  165         }
  166         self.inside_public_path = orig_inside_public_path;
  167         om
  168     }
  169 
  170     /// Tries to resolve the target of a `pub use` statement and inlines the
  171     /// target if it is defined locally and would not be documented otherwise,
  172     /// or when it is specifically requested with `please_inline`.
  173     /// (the latter is the case when the import is marked `doc(inline)`)
  174     ///
  175     /// Cross-crate inlining occurs later on during crate cleaning
  176     /// and follows different rules.
  177     ///
  178     /// Returns `true` if the target has been inlined.
  179     fn maybe_inline_local(
  180         &mut self,
  181         id: hir::HirId,
  182         res: Res,
  183         renamed: Option<Symbol>,
  184         glob: bool,
  185         om: &mut Module<'tcx>,
  186         please_inline: bool,
  187     ) -> bool {
  188         debug!("maybe_inline_local res: {:?}", res);
  189 
  190         let tcx = self.cx.tcx;
  191         let Some(res_did) = res.opt_def_id() else {
  192             return false;
  193         };
  194 
  195         let use_attrs = tcx.hir().attrs(id);
  196         // Don't inline `doc(hidden)` imports so they can be stripped at a later stage.
  197         let is_no_inline = use_attrs.lists(sym::doc).has_word(sym::no_inline)
  198             || use_attrs.lists(sym::doc).has_word(sym::hidden);
  199 
  200         // For cross-crate impl inlining we need to know whether items are
  201         // reachable in documentation -- a previously unreachable item can be
  202         // made reachable by cross-crate inlining which we're checking here.
  203         // (this is done here because we need to know this upfront).
  204         if !res_did.is_local() && !is_no_inline {
  205             let attrs = clean::inline::load_attrs(self.cx, res_did);
  206             let self_is_hidden = attrs.lists(sym::doc).has_word(sym::hidden);
  207             if !self_is_hidden {
  208                 if let Res::Def(kind, did) = res {
  209                     if kind == DefKind::Mod {
  210                         crate::visit_lib::LibEmbargoVisitor::new(self.cx).visit_mod(did)
  211                     } else {
  212                         // All items need to be handled here in case someone wishes to link
  213                         // to them with intra-doc links
  214                         self.cx.cache.access_levels.map.insert(did, AccessLevel::Public);
  215                     }
  216                 }
  217             }
  218             return false;
  219         }
  220 
  221         let res_hir_id = match res_did.as_local() {
  222             Some(n) => tcx.hir().local_def_id_to_hir_id(n),
  223             None => return false,
  224         };
  225 
  226         let is_private = !self.cx.cache.access_levels.is_public(res_did);
  227         let is_hidden = inherits_doc_hidden(self.cx.tcx, res_hir_id);
  228 
  229         // Only inline if requested or if the item would otherwise be stripped.
  230         if (!please_inline && !is_private && !is_hidden) || is_no_inline {
  231             return false;
  232         }
  233 
  234         if !self.view_item_stack.insert(res_hir_id) {
  235             return false;
  236         }
  237 
  238         let ret = match tcx.hir().get(res_hir_id) {
  239             Node::Item(&hir::Item { kind: hir::ItemKind::Mod(ref m), .. }) if glob => {
  240                 let prev = mem::replace(&mut self.inlining, true);
  241                 for &i in m.item_ids {
  242                     let i = self.cx.tcx.hir().item(i);
  243                     self.visit_item(i, None, om);
  244                 }
  245                 self.inlining = prev;
  246                 true
  247             }
  248             Node::Item(it) if !glob => {
  249                 let prev = mem::replace(&mut self.inlining, true);
  250                 self.visit_item(it, renamed, om);
  251                 self.inlining = prev;
  252                 true
  253             }
  254             Node::ForeignItem(it) if !glob => {
  255                 let prev = mem::replace(&mut self.inlining, true);
  256                 self.visit_foreign_item(it, renamed, om);
  257                 self.inlining = prev;
  258                 true
  259             }
  260             _ => false,
  261         };
  262         self.view_item_stack.remove(&res_hir_id);
  263         ret
  264     }
  265 
  266     fn visit_item(
  267         &mut self,
  268         item: &'tcx hir::Item<'_>,
  269         renamed: Option<Symbol>,
  270         om: &mut Module<'tcx>,
  271     ) {
  272         debug!("visiting item {:?}", item);
  273         let name = renamed.unwrap_or(item.ident.name);
  274 
  275         let def_id = item.def_id.to_def_id();
  276         let is_pub = self.cx.tcx.visibility(def_id).is_public();
  277 
  278         if is_pub {
  279             self.store_path(item.def_id.to_def_id());
  280         }
  281 
  282         match item.kind {
  283             hir::ItemKind::ForeignMod { items, .. } => {
  284                 for item in items {
  285                     let item = self.cx.tcx.hir().foreign_item(item.id);
  286                     self.visit_foreign_item(item, None, om);
  287                 }
  288             }
  289             // If we're inlining, skip private items.
  290             _ if self.inlining && !is_pub => {}
  291             hir::ItemKind::GlobalAsm(..) => {}
  292             hir::ItemKind::Use(_, hir::UseKind::ListStem) => {}
  293             hir::ItemKind::Use(path, kind) => {
  294                 let is_glob = kind == hir::UseKind::Glob;
  295 
  296                 // Struct and variant constructors and proc macro stubs always show up alongside
  297                 // their definitions, we've already processed them so just discard these.
  298                 if let Res::Def(DefKind::Ctor(..), _) | Res::SelfCtor(..) = path.res {
  299                     return;
  300                 }
  301 
  302                 let attrs = self.cx.tcx.hir().attrs(item.hir_id());
  303 
  304                 // If there was a private module in the current path then don't bother inlining
  305                 // anything as it will probably be stripped anyway.
  306                 if is_pub && self.inside_public_path {
  307                     let please_inline = attrs.iter().any(|item| match item.meta_item_list() {
  308                         Some(ref list) if item.has_name(sym::doc) => {
  309                             list.iter().any(|i| i.has_name(sym::inline))
  310                         }
  311                         _ => false,
  312                     });
  313                     let ident = if is_glob { None } else { Some(name) };
  314                     if self.maybe_inline_local(
  315                         item.hir_id(),
  316                         path.res,
  317                         ident,
  318                         is_glob,
  319                         om,
  320                         please_inline,
  321                     ) {
  322                         return;
  323                     }
  324                 }
  325 
  326                 om.items.push((item, renamed))
  327             }
  328             hir::ItemKind::Macro(ref macro_def) => {
  329                 // `#[macro_export] macro_rules!` items are handled seperately in `visit()`,
  330                 // above, since they need to be documented at the module top level. Accordingly,
  331                 // we only want to handle macros if one of three conditions holds:
  332                 //
  333                 // 1. This macro was defined by `macro`, and thus isn't covered by the case
  334                 //    above.
  335                 // 2. This macro isn't marked with `#[macro_export]`, and thus isn't covered
  336                 //    by the case above.
  337                 // 3. We're inlining, since a reexport where inlining has been requested
  338                 //    should be inlined even if it is also documented at the top level.
  339 
  340                 let def_id = item.def_id.to_def_id();
  341                 let is_macro_2_0 = !macro_def.macro_rules;
  342                 let nonexported = !self.cx.tcx.has_attr(def_id, sym::macro_export);
  343 
  344                 if is_macro_2_0 || nonexported || self.inlining {
  345                     om.items.push((item, renamed));
  346                 }
  347             }
  348             hir::ItemKind::Mod(ref m) => {
  349                 om.mods.push(self.visit_mod_contents(item.hir_id(), m, name));
  350             }
  351             hir::ItemKind::Fn(..)
  352             | hir::ItemKind::ExternCrate(..)
  353             | hir::ItemKind::Enum(..)
  354             | hir::ItemKind::Struct(..)
  355             | hir::ItemKind::Union(..)
  356             | hir::ItemKind::TyAlias(..)
  357             | hir::ItemKind::OpaqueTy(..)
  358             | hir::ItemKind::Static(..)
  359             | hir::ItemKind::Trait(..)
  360             | hir::ItemKind::TraitAlias(..) => om.items.push((item, renamed)),
  361             hir::ItemKind::Const(..) => {
  362                 // Underscore constants do not correspond to a nameable item and
  363                 // so are never useful in documentation.
  364                 if name != kw::Underscore {
  365                     om.items.push((item, renamed));
  366                 }
  367             }
  368             hir::ItemKind::Impl(ref impl_) => {
  369                 // Don't duplicate impls when inlining or if it's implementing a trait, we'll pick
  370                 // them up regardless of where they're located.
  371                 if !self.inlining && impl_.of_trait.is_none() {
  372                     om.items.push((item, None));
  373                 }
  374             }
  375         }
  376     }
  377 
  378     fn visit_foreign_item(
  379         &mut self,
  380         item: &'tcx hir::ForeignItem<'_>,
  381         renamed: Option<Symbol>,
  382         om: &mut Module<'tcx>,
  383     ) {
  384         // If inlining we only want to include public functions.
  385         if !self.inlining || self.cx.tcx.visibility(item.def_id).is_public() {
  386             om.foreigns.push((item, renamed));
  387         }
  388     }
  389 }