src/librustdoc/stability_summary.rs

   1 // Copyright 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 //! This module crawls a `clean::Crate` and produces a summarization of the
  12 //! stability levels within the crate. The summary contains the module
  13 //! hierarchy, with item counts for every stability level per module. A parent
  14 //! module's count includes its children's.
  15
  16 use std::cmp::Ordering;
  17 use std::ops::Add;
  18
  19 use syntax::attr::{Deprecated, Experimental, Unstable, Stable, Frozen, Locked};
  20 use syntax::ast::Public;
  21
  22 use clean::{Crate, Item, ModuleItem, Module, EnumItem, Enum};
  23 use clean::{ImplItem, Impl, Trait, TraitItem, TraitMethod, ProvidedMethod, RequiredMethod};
  24 use clean::{TypeTraitItem, ViewItemItem, PrimitiveItem, Stability};
  25
  26 use html::render::cache;
  27
  28 #[derive(RustcEncodable, RustcDecodable, PartialEq, Eq)]
  29 /// The counts for each stability level.
  30 #[derive(Copy)]
  31 pub struct Counts {
  32     pub deprecated: uint,
  33     pub experimental: uint,
  34     pub unstable: uint,
  35     pub stable: uint,
  36     pub frozen: uint,
  37     pub locked: uint,
  38
  39     /// No stability level, inherited or otherwise.
  40     pub unmarked: uint,
  41 }
  42
  43 impl Add for Counts {
  44     type Output = Counts;
  45
  46     fn add(self, other: Counts) -> Counts {
  47         Counts {
  48             deprecated:   self.deprecated   + other.deprecated,
  49             experimental: self.experimental + other.experimental,
  50             unstable:     self.unstable     + other.unstable,
  51             stable:       self.stable       + other.stable,
  52             frozen:       self.frozen       + other.frozen,
  53             locked:       self.locked       + other.locked,
  54             unmarked:     self.unmarked     + other.unmarked,
  55         }
  56     }
  57 }
  58
  59 impl Counts {
  60     fn zero() -> Counts {
  61         Counts {
  62             deprecated:   0,
  63             experimental: 0,
  64             unstable:     0,
  65             stable:       0,
  66             frozen:       0,
  67             locked:       0,
  68             unmarked:     0,
  69         }
  70     }
  71
  72     pub fn total(&self) -> uint {
  73         self.deprecated + self.experimental + self.unstable + self.stable +
  74             self.frozen + self.locked + self.unmarked
  75     }
  76 }
  77
  78 #[derive(RustcEncodable, RustcDecodable, PartialEq, Eq)]
  79 /// A summarized module, which includes total counts and summarized children
  80 /// modules.
  81 pub struct ModuleSummary {
  82     pub name: String,
  83     pub counts: Counts,
  84     pub submodules: Vec<ModuleSummary>,
  85 }
  86
  87 impl PartialOrd for ModuleSummary {
  88     fn partial_cmp(&self, other: &ModuleSummary) -> Option<Ordering> {
  89         self.name.partial_cmp(&other.name)
  90     }
  91 }
  92
  93 impl Ord for ModuleSummary {
  94     fn cmp(&self, other: &ModuleSummary) -> Ordering {
  95         self.name.cmp(&other.name)
  96     }
  97 }
  98
  99 // is the item considered publically visible?
 100 fn visible(item: &Item) -> bool {
 101     match item.inner {
 102         ImplItem(_) => true,
 103         _ => item.visibility == Some(Public)
 104     }
 105 }
 106
 107 fn count_stability(stab: Option<&Stability>) -> Counts {
 108     match stab {
 109         None             => Counts { unmarked: 1,     .. Counts::zero() },
 110         Some(ref stab) => match stab.level {
 111             Deprecated   => Counts { deprecated: 1,   .. Counts::zero() },
 112             Experimental => Counts { experimental: 1, .. Counts::zero() },
 113             Unstable     => Counts { unstable: 1,     .. Counts::zero() },
 114             Stable       => Counts { stable: 1,       .. Counts::zero() },
 115             Frozen       => Counts { frozen: 1,       .. Counts::zero() },
 116             Locked       => Counts { locked: 1,       .. Counts::zero() },
 117         }
 118     }
 119 }
 120
 121 fn summarize_methods(item: &Item) -> Counts {
 122     match cache().impls.get(&item.def_id) {
 123         Some(v) => {
 124             v.iter().map(|i| {
 125                 let count = count_stability(i.stability.as_ref());
 126                 if i.impl_.trait_.is_none() {
 127                     count + i.impl_.items.iter()
 128                         .map(|ti| summarize_item(ti).0)
 129                         .fold(Counts::zero(), |acc, c| acc + c)
 130                 } else {
 131                     count
 132                 }
 133             }).fold(Counts::zero(), |acc, c| acc + c)
 134         },
 135         None => {
 136             Counts::zero()
 137         },
 138     }
 139 }
 140
 141
 142 // Produce the summary for an arbitrary item. If the item is a module, include a
 143 // module summary. The counts for items with nested items (e.g. modules, traits,
 144 // impls) include all children counts.
 145 fn summarize_item(item: &Item) -> (Counts, Option<ModuleSummary>) {
 146     let item_counts = count_stability(item.stability.as_ref()) + summarize_methods(item);
 147
 148     // Count this item's children, if any. Note that a trait impl is
 149     // considered to have no children.
 150     match item.inner {
 151         // Require explicit `pub` to be visible
 152         ImplItem(Impl { items: ref subitems, trait_: None, .. }) => {
 153             let subcounts = subitems.iter().filter(|i| visible(*i))
 154                                            .map(summarize_item)
 155                                            .map(|s| s.0)
 156                                            .fold(Counts::zero(), |acc, x| acc + x);
 157             (subcounts, None)
 158         }
 159         // `pub` automatically
 160         EnumItem(Enum { variants: ref subitems, .. }) => {
 161             let subcounts = subitems.iter().map(summarize_item)
 162                                            .map(|s| s.0)
 163                                            .fold(Counts::zero(), |acc, x| acc + x);
 164             (item_counts + subcounts, None)
 165         }
 166         TraitItem(Trait {
 167             items: ref trait_items,
 168             ..
 169         }) => {
 170             fn extract_item<'a>(trait_item: &'a TraitMethod) -> &'a Item {
 171                 match *trait_item {
 172                     ProvidedMethod(ref item) |
 173                     RequiredMethod(ref item) |
 174                     TypeTraitItem(ref item) => item
 175                 }
 176             }
 177             let subcounts = trait_items.iter()
 178                                        .map(extract_item)
 179                                        .map(summarize_item)
 180                                        .map(|s| s.0)
 181                                        .fold(Counts::zero(), |acc, x| acc + x);
 182             (item_counts + subcounts, None)
 183         }
 184         ModuleItem(Module { ref items, .. }) => {
 185             let mut counts = item_counts;
 186             let mut submodules = Vec::new();
 187
 188             for (subcounts, submodule) in items.iter().filter(|i| visible(*i))
 189                                                       .map(summarize_item) {
 190                 counts = counts + subcounts;
 191                 submodule.map(|m| submodules.push(m));
 192             }
 193             submodules.sort();
 194
 195             (counts, Some(ModuleSummary {
 196                 name: item.name.as_ref().map_or("".to_string(), |n| n.clone()),
 197                 counts: counts,
 198                 submodules: submodules,
 199             }))
 200         }
 201         // no stability information for the following items:
 202         ViewItemItem(_) | PrimitiveItem(_) => (Counts::zero(), None),
 203         _ => (item_counts, None)
 204     }
 205 }
 206
 207 /// Summarizes the stability levels in a crate.
 208 pub fn build(krate: &Crate) -> ModuleSummary {
 209     match krate.module {
 210         None => ModuleSummary {
 211             name: krate.name.clone(),
 212             counts: Counts::zero(),
 213             submodules: Vec::new(),
 214         },
 215         Some(ref item) => ModuleSummary {
 216             name: krate.name.clone(), .. summarize_item(item).1.unwrap()
 217         }
 218     }
 219 }