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, ItemId, ItemIdSet};
   7 use crate::fold::{strip_item, DocFolder};
   8 use crate::formats::cache::Cache;
   9
  10 pub(crate) struct Stripper<'a> {
  11     pub(crate) retained: &'a mut ItemIdSet,
  12     pub(crate) access_levels: &'a AccessLevels<DefId>,
  13     pub(crate) update_retained: bool,
  14     pub(crate) is_json_output: bool,
  15 }
  16
  17 // We need to handle this differently for the JSON output because some non exported items could
  18 // be used in public API. And so, we need these items as well. `is_exported` only checks if they
  19 // are in the public API, which is not enough.
  20 #[inline]
  21 fn is_item_reachable(
  22     is_json_output: bool,
  23     access_levels: &AccessLevels<DefId>,
  24     item_id: ItemId,
  25 ) -> bool {
  26     if is_json_output {
  27         access_levels.is_reachable(item_id.expect_def_id())
  28     } else {
  29         access_levels.is_exported(item_id.expect_def_id())
  30     }
  31 }
  32
  33 impl<'a> DocFolder for Stripper<'a> {
  34     fn fold_item(&mut self, i: Item) -> Option<Item> {
  35         match *i.kind {
  36             clean::StrippedItem(..) => {
  37                 // We need to recurse into stripped modules to strip things
  38                 // like impl methods but when doing so we must not add any
  39                 // items to the `retained` set.
  40                 debug!("Stripper: recursing into stripped {:?} {:?}", i.type_(), i.name);
  41                 let old = mem::replace(&mut self.update_retained, false);
  42                 let ret = self.fold_item_recur(i);
  43                 self.update_retained = old;
  44                 return Some(ret);
  45             }
  46             // These items can all get re-exported
  47             clean::OpaqueTyItem(..)
  48             | clean::TypedefItem(..)
  49             | clean::StaticItem(..)
  50             | clean::StructItem(..)
  51             | clean::EnumItem(..)
  52             | clean::TraitItem(..)
  53             | clean::FunctionItem(..)
  54             | clean::VariantItem(..)
  55             | clean::MethodItem(..)
  56             | clean::ForeignFunctionItem(..)
  57             | clean::ForeignStaticItem(..)
  58             | clean::ConstantItem(..)
  59             | clean::UnionItem(..)
  60             | clean::AssocConstItem(..)
  61             | clean::AssocTypeItem(..)
  62             | clean::TraitAliasItem(..)
  63             | clean::MacroItem(..)
  64             | clean::ForeignTypeItem => {
  65                 let item_id = i.item_id;
  66                 if item_id.is_local()
  67                     && !is_item_reachable(self.is_json_output, self.access_levels, item_id)
  68                 {
  69                     debug!("Stripper: stripping {:?} {:?}", i.type_(), i.name);
  70                     return None;
  71                 }
  72             }
  73
  74             clean::StructFieldItem(..) => {
  75                 if !i.visibility.is_public() {
  76                     return Some(strip_item(i));
  77                 }
  78             }
  79
  80             clean::ModuleItem(..) => {
  81                 if i.item_id.is_local() && !i.visibility.is_public() {
  82                     debug!("Stripper: stripping module {:?}", i.name);
  83                     let old = mem::replace(&mut self.update_retained, false);
  84                     let ret = strip_item(self.fold_item_recur(i));
  85                     self.update_retained = old;
  86                     return Some(ret);
  87                 }
  88             }
  89
  90             // handled in the `strip-priv-imports` pass
  91             clean::ExternCrateItem { .. } | clean::ImportItem(..) => {}
  92
  93             clean::ImplItem(..) => {}
  94
  95             // tymethods etc. have no control over privacy
  96             clean::TyMethodItem(..) | clean::TyAssocConstItem(..) | clean::TyAssocTypeItem(..) => {}
  97
  98             // Proc-macros are always public
  99             clean::ProcMacroItem(..) => {}
 100
 101             // Primitives are never stripped
 102             clean::PrimitiveItem(..) => {}
 103
 104             // Keywords are never stripped
 105             clean::KeywordItem => {}
 106         }
 107
 108         let fastreturn = match *i.kind {
 109             // nothing left to do for traits (don't want to filter their
 110             // methods out, visibility controlled by the trait)
 111             clean::TraitItem(..) => true,
 112
 113             // implementations of traits are always public.
 114             clean::ImplItem(ref imp) if imp.trait_.is_some() => true,
 115             // Variant fields have inherited visibility
 116             clean::VariantItem(clean::Variant::Struct(..) | clean::Variant::Tuple(..)) => true,
 117             _ => false,
 118         };
 119
 120         let i = if fastreturn {
 121             if self.update_retained {
 122                 self.retained.insert(i.item_id);
 123             }
 124             return Some(i);
 125         } else {
 126             self.fold_item_recur(i)
 127         };
 128
 129         if self.update_retained {
 130             self.retained.insert(i.item_id);
 131         }
 132         Some(i)
 133     }
 134 }
 135
 136 /// This stripper discards all impls which reference stripped items
 137 pub(crate) struct ImplStripper<'a> {
 138     pub(crate) retained: &'a ItemIdSet,
 139     pub(crate) cache: &'a Cache,
 140     pub(crate) is_json_output: bool,
 141     pub(crate) document_private: bool,
 142 }
 143
 144 impl<'a> DocFolder for ImplStripper<'a> {
 145     fn fold_item(&mut self, i: Item) -> Option<Item> {
 146         if let clean::ImplItem(ref imp) = *i.kind {
 147             // Impl blocks can be skipped if they are: empty; not a trait impl; and have no
 148             // documentation.
 149             //
 150             // There is one special case: if the impl block contains only private items.
 151             if imp.trait_.is_none() {
 152                 // If the only items present are private ones and we're not rendering private items,
 153                 // we don't document it.
 154                 if !imp.items.is_empty()
 155                     && !self.document_private
 156                     && imp.items.iter().all(|i| {
 157                         let item_id = i.item_id;
 158                         item_id.is_local()
 159                             && !is_item_reachable(
 160                                 self.is_json_output,
 161                                 &self.cache.access_levels,
 162                                 item_id,
 163                             )
 164                     })
 165                 {
 166                     return None;
 167                 } else if imp.items.is_empty() && i.doc_value().is_none() {
 168                     return None;
 169                 }
 170             }
 171             if let Some(did) = imp.for_.def_id(self.cache) {
 172                 if did.is_local() && !imp.for_.is_assoc_ty() && !self.retained.contains(&did.into())
 173                 {
 174                     debug!("ImplStripper: impl item for stripped type; removing");
 175                     return None;
 176                 }
 177             }
 178             if let Some(did) = imp.trait_.as_ref().map(|t| t.def_id()) {
 179                 if did.is_local() && !self.retained.contains(&did.into()) {
 180                     debug!("ImplStripper: impl item for stripped trait; removing");
 181                     return None;
 182                 }
 183             }
 184             if let Some(generics) = imp.trait_.as_ref().and_then(|t| t.generics()) {
 185                 for typaram in generics {
 186                     if let Some(did) = typaram.def_id(self.cache) {
 187                         if did.is_local() && !self.retained.contains(&did.into()) {
 188                             debug!(
 189                                 "ImplStripper: stripped item in trait's generics; removing impl"
 190                             );
 191                             return None;
 192                         }
 193                     }
 194                 }
 195             }
 196         }
 197         Some(self.fold_item_recur(i))
 198     }
 199 }
 200
 201 /// This stripper discards all private import statements (`use`, `extern crate`)
 202 pub(crate) struct ImportStripper;
 203
 204 impl DocFolder for ImportStripper {
 205     fn fold_item(&mut self, i: Item) -> Option<Item> {
 206         match *i.kind {
 207             clean::ExternCrateItem { .. } | clean::ImportItem(..) if !i.visibility.is_public() => {
 208                 None
 209             }
 210             _ => Some(self.fold_item_recur(i)),
 211         }
 212     }
 213 }