src/librustdoc/passes/stripper.rs

   1 //! A collection of utility functions for the `strip_*` passes.
   2 use rustc_hir::def_id::DefId;
   3 use rustc_middle::middle::privacy::AccessLevels;
   4 use std::mem;
   5
   6 use crate::clean::{self, Item, ItemIdSet};
   7 use crate::fold::{strip_item, DocFolder};
   8
   9 crate struct Stripper<'a> {
  10     crate retained: &'a mut ItemIdSet,
  11     crate access_levels: &'a AccessLevels<DefId>,
  12     crate update_retained: bool,
  13 }
  14
  15 impl<'a> DocFolder for Stripper<'a> {
  16     fn fold_item(&mut self, i: Item) -> Option<Item> {
  17         match *i.kind {
  18             clean::StrippedItem(..) => {
  19                 // We need to recurse into stripped modules to strip things
  20                 // like impl methods but when doing so we must not add any
  21                 // items to the `retained` set.
  22                 debug!("Stripper: recursing into stripped {:?} {:?}", i.type_(), i.name);
  23                 let old = mem::replace(&mut self.update_retained, false);
  24                 let ret = self.fold_item_recur(i);
  25                 self.update_retained = old;
  26                 return Some(ret);
  27             }
  28             // These items can all get re-exported
  29             clean::OpaqueTyItem(..)
  30             | clean::TypedefItem(..)
  31             | clean::StaticItem(..)
  32             | clean::StructItem(..)
  33             | clean::EnumItem(..)
  34             | clean::TraitItem(..)
  35             | clean::FunctionItem(..)
  36             | clean::VariantItem(..)
  37             | clean::MethodItem(..)
  38             | clean::ForeignFunctionItem(..)
  39             | clean::ForeignStaticItem(..)
  40             | clean::ConstantItem(..)
  41             | clean::UnionItem(..)
  42             | clean::AssocConstItem(..)
  43             | clean::TraitAliasItem(..)
  44             | clean::MacroItem(..)
  45             | clean::ForeignTypeItem => {
  46                 if i.def_id.is_local() && !self.access_levels.is_exported(i.def_id.expect_def_id())
  47                 {
  48                     debug!("Stripper: stripping {:?} {:?}", i.type_(), i.name);
  49                     return None;
  50                 }
  51             }
  52
  53             clean::StructFieldItem(..) => {
  54                 if !i.visibility.is_public() {
  55                     return Some(strip_item(i));
  56                 }
  57             }
  58
  59             clean::ModuleItem(..) => {
  60                 if i.def_id.is_local() && !i.visibility.is_public() {
  61                     debug!("Stripper: stripping module {:?}", i.name);
  62                     let old = mem::replace(&mut self.update_retained, false);
  63                     let ret = strip_item(self.fold_item_recur(i));
  64                     self.update_retained = old;
  65                     return Some(ret);
  66                 }
  67             }
  68
  69             // handled in the `strip-priv-imports` pass
  70             clean::ExternCrateItem { .. } | clean::ImportItem(..) => {}
  71
  72             clean::ImplItem(..) => {}
  73
  74             // tymethods have no control over privacy
  75             clean::TyMethodItem(..) => {}
  76
  77             // Proc-macros are always public
  78             clean::ProcMacroItem(..) => {}
  79
  80             // Primitives are never stripped
  81             clean::PrimitiveItem(..) => {}
  82
  83             // Associated types are never stripped
  84             clean::AssocTypeItem(..) => {}
  85
  86             // Keywords are never stripped
  87             clean::KeywordItem(..) => {}
  88         }
  89
  90         let fastreturn = match *i.kind {
  91             // nothing left to do for traits (don't want to filter their
  92             // methods out, visibility controlled by the trait)
  93             clean::TraitItem(..) => true,
  94
  95             // implementations of traits are always public.
  96             clean::ImplItem(ref imp) if imp.trait_.is_some() => true,
  97             // Variant fields have inherited visibility
  98             clean::VariantItem(clean::Variant::Struct(..) | clean::Variant::Tuple(..)) => true,
  99             _ => false,
 100         };
 101
 102         let i = if fastreturn {
 103             if self.update_retained {
 104                 self.retained.insert(i.def_id);
 105             }
 106             return Some(i);
 107         } else {
 108             self.fold_item_recur(i)
 109         };
 110
 111         if self.update_retained {
 112             self.retained.insert(i.def_id);
 113         }
 114         Some(i)
 115     }
 116 }
 117
 118 /// This stripper discards all impls which reference stripped items
 119 crate struct ImplStripper<'a> {
 120     crate retained: &'a ItemIdSet,
 121 }
 122
 123 impl<'a> DocFolder for ImplStripper<'a> {
 124     fn fold_item(&mut self, i: Item) -> Option<Item> {
 125         if let clean::ImplItem(ref imp) = *i.kind {
 126             // emptied none trait impls can be stripped
 127             if imp.trait_.is_none() && imp.items.is_empty() {
 128                 return None;
 129             }
 130             if let Some(did) = imp.for_.def_id_no_primitives() {
 131                 if did.is_local() && !imp.for_.is_assoc_ty() && !self.retained.contains(&did.into())
 132                 {
 133                     debug!("ImplStripper: impl item for stripped type; removing");
 134                     return None;
 135                 }
 136             }
 137             if let Some(did) = imp.trait_.as_ref().map(|t| t.def_id()) {
 138                 if did.is_local() && !self.retained.contains(&did.into()) {
 139                     debug!("ImplStripper: impl item for stripped trait; removing");
 140                     return None;
 141                 }
 142             }
 143             if let Some(generics) = imp.trait_.as_ref().and_then(|t| t.generics()) {
 144                 for typaram in generics {
 145                     if let Some(did) = typaram.def_id_no_primitives() {
 146                         if did.is_local() && !self.retained.contains(&did.into()) {
 147                             debug!(
 148                                 "ImplStripper: stripped item in trait's generics; removing impl"
 149                             );
 150                             return None;
 151                         }
 152                     }
 153                 }
 154             }
 155         }
 156         Some(self.fold_item_recur(i))
 157     }
 158 }
 159
 160 /// This stripper discards all private import statements (`use`, `extern crate`)
 161 crate struct ImportStripper;
 162
 163 impl DocFolder for ImportStripper {
 164     fn fold_item(&mut self, i: Item) -> Option<Item> {
 165         match *i.kind {
 166             clean::ExternCrateItem { .. } | clean::ImportItem(..) if !i.visibility.is_public() => {
 167                 None
 168             }
 169             _ => Some(self.fold_item_recur(i)),
 170         }
 171     }
 172 }