src/librustdoc/passes/mod.rs

   1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 use rustc::hir::def_id::DefId;
  12 use rustc::middle::privacy::AccessLevels;
  13 use rustc::util::nodemap::DefIdSet;
  14 use std::mem;
  15
  16 use clean::{self, GetDefId, Item};
  17 use fold;
  18 use fold::FoldItem::Strip;
  19 use plugins;
  20
  21 mod collapse_docs;
  22 pub use self::collapse_docs::collapse_docs;
  23
  24 mod strip_hidden;
  25 pub use self::strip_hidden::strip_hidden;
  26
  27 mod strip_private;
  28 pub use self::strip_private::strip_private;
  29
  30 mod strip_priv_imports;
  31 pub use self::strip_priv_imports::strip_priv_imports;
  32
  33 mod unindent_comments;
  34 pub use self::unindent_comments::unindent_comments;
  35
  36 mod propagate_doc_cfg;
  37 pub use self::propagate_doc_cfg::propagate_doc_cfg;
  38
  39 type Pass = (&'static str,                                      // name
  40              fn(clean::Crate) -> plugins::PluginResult,         // fn
  41              &'static str);                                     // description
  42
  43 pub const PASSES: &'static [Pass] = &[
  44     ("strip-hidden", strip_hidden,
  45      "strips all doc(hidden) items from the output"),
  46     ("unindent-comments", unindent_comments,
  47      "removes excess indentation on comments in order for markdown to like it"),
  48     ("collapse-docs", collapse_docs,
  49      "concatenates all document attributes into one document attribute"),
  50     ("strip-private", strip_private,
  51      "strips all private items from a crate which cannot be seen externally, \
  52       implies strip-priv-imports"),
  53     ("strip-priv-imports", strip_priv_imports,
  54      "strips all private import statements (`use`, `extern crate`) from a crate"),
  55     ("propagate-doc-cfg", propagate_doc_cfg,
  56      "propagates `#[doc(cfg(...))]` to child items"),
  57 ];
  58
  59 pub const DEFAULT_PASSES: &'static [&'static str] = &[
  60     "strip-hidden",
  61     "strip-private",
  62     "collapse-docs",
  63     "unindent-comments",
  64     "propagate-doc-cfg",
  65 ];
  66
  67
  68 struct Stripper<'a> {
  69     retained: &'a mut DefIdSet,
  70     access_levels: &'a AccessLevels<DefId>,
  71     update_retained: bool,
  72 }
  73
  74 impl<'a> fold::DocFolder for Stripper<'a> {
  75     fn fold_item(&mut self, i: Item) -> Option<Item> {
  76         match i.inner {
  77             clean::StrippedItem(..) => {
  78                 // We need to recurse into stripped modules to strip things
  79                 // like impl methods but when doing so we must not add any
  80                 // items to the `retained` set.
  81                 let old = mem::replace(&mut self.update_retained, false);
  82                 let ret = self.fold_item_recur(i);
  83                 self.update_retained = old;
  84                 return ret;
  85             }
  86             // These items can all get re-exported
  87             clean::TypedefItem(..) | clean::StaticItem(..) |
  88             clean::StructItem(..) | clean::EnumItem(..) |
  89             clean::TraitItem(..) | clean::FunctionItem(..) |
  90             clean::VariantItem(..) | clean::MethodItem(..) |
  91             clean::ForeignFunctionItem(..) | clean::ForeignStaticItem(..) |
  92             clean::ConstantItem(..) | clean::UnionItem(..) |
  93             clean::AssociatedConstItem(..) | clean::ForeignTypeItem => {
  94                 if i.def_id.is_local() {
  95                     if !self.access_levels.is_exported(i.def_id) {
  96                         return None;
  97                     }
  98                 }
  99             }
 100
 101             clean::StructFieldItem(..) => {
 102                 if i.visibility != Some(clean::Public) {
 103                     return Strip(i).fold();
 104                 }
 105             }
 106
 107             clean::ModuleItem(..) => {
 108                 if i.def_id.is_local() && i.visibility != Some(clean::Public) {
 109                     let old = mem::replace(&mut self.update_retained, false);
 110                     let ret = Strip(self.fold_item_recur(i).unwrap()).fold();
 111                     self.update_retained = old;
 112                     return ret;
 113                 }
 114             }
 115
 116             // handled in the `strip-priv-imports` pass
 117             clean::ExternCrateItem(..) | clean::ImportItem(..) => {}
 118
 119             clean::ImplItem(..) => {}
 120
 121             // tymethods/macros have no control over privacy
 122             clean::MacroItem(..) | clean::TyMethodItem(..) => {}
 123
 124             // Primitives are never stripped
 125             clean::PrimitiveItem(..) => {}
 126
 127             // Associated types are never stripped
 128             clean::AssociatedTypeItem(..) => {}
 129
 130             // Keywords are never stripped
 131             clean::KeywordItem(..) => {}
 132         }
 133
 134         let fastreturn = match i.inner {
 135             // nothing left to do for traits (don't want to filter their
 136             // methods out, visibility controlled by the trait)
 137             clean::TraitItem(..) => true,
 138
 139             // implementations of traits are always public.
 140             clean::ImplItem(ref imp) if imp.trait_.is_some() => true,
 141             // Struct variant fields have inherited visibility
 142             clean::VariantItem(clean::Variant {
 143                 kind: clean::VariantKind::Struct(..)
 144             }) => true,
 145             _ => false,
 146         };
 147
 148         let i = if fastreturn {
 149             if self.update_retained {
 150                 self.retained.insert(i.def_id);
 151             }
 152             return Some(i);
 153         } else {
 154             self.fold_item_recur(i)
 155         };
 156
 157         if let Some(ref i) = i {
 158             if self.update_retained {
 159                 self.retained.insert(i.def_id);
 160             }
 161         }
 162         i
 163     }
 164 }
 165
 166 // This stripper discards all impls which reference stripped items
 167 struct ImplStripper<'a> {
 168     retained: &'a DefIdSet
 169 }
 170
 171 impl<'a> fold::DocFolder for ImplStripper<'a> {
 172     fn fold_item(&mut self, i: Item) -> Option<Item> {
 173         if let clean::ImplItem(ref imp) = i.inner {
 174             // emptied none trait impls can be stripped
 175             if imp.trait_.is_none() && imp.items.is_empty() {
 176                 return None;
 177             }
 178             if let Some(did) = imp.for_.def_id() {
 179                 if did.is_local() && !imp.for_.is_generic() &&
 180                     !self.retained.contains(&did)
 181                 {
 182                     return None;
 183                 }
 184             }
 185             if let Some(did) = imp.trait_.def_id() {
 186                 if did.is_local() && !self.retained.contains(&did) {
 187                     return None;
 188                 }
 189             }
 190             if let Some(generics) = imp.trait_.as_ref().and_then(|t| t.generics()) {
 191                 for typaram in generics {
 192                     if let Some(did) = typaram.def_id() {
 193                         if did.is_local() && !self.retained.contains(&did) {
 194                             return None;
 195                         }
 196                     }
 197                 }
 198             }
 199         }
 200         self.fold_item_recur(i)
 201     }
 202 }
 203
 204 // This stripper discards all private import statements (`use`, `extern crate`)
 205 struct ImportStripper;
 206 impl fold::DocFolder for ImportStripper {
 207     fn fold_item(&mut self, i: Item) -> Option<Item> {
 208         match i.inner {
 209             clean::ExternCrateItem(..) |
 210             clean::ImportItem(..) if i.visibility != Some(clean::Public) => None,
 211             _ => self.fold_item_recur(i)
 212         }
 213     }
 214 }