src/librustdoc/clean/simplify.rs

   1 //! Simplification of where-clauses and parameter bounds into a prettier and
   2 //! more canonical form.
   3 //!
   4 //! Currently all cross-crate-inlined function use `rustc::ty` to reconstruct
   5 //! the AST (e.g., see all of `clean::inline`), but this is not always a
   6 //! non-lossy transformation. The current format of storage for where-clauses
   7 //! for functions and such is simply a list of predicates. One example of this
   8 //! is that the AST predicate of: `where T: Trait<Foo = Bar>` is encoded as:
   9 //! `where T: Trait, <T as Trait>::Foo = Bar`.
  10 //!
  11 //! This module attempts to reconstruct the original where and/or parameter
  12 //! bounds by special casing scenarios such as these. Fun!
  13
  14 use std::mem;
  15 use std::collections::BTreeMap;
  16
  17 use rustc::hir::def_id::DefId;
  18 use rustc::ty;
  19
  20 use crate::clean::GenericArgs as PP;
  21 use crate::clean::WherePredicate as WP;
  22 use crate::clean;
  23 use crate::core::DocContext;
  24
  25 pub fn where_clauses(cx: &DocContext<'_>, clauses: Vec<WP>) -> Vec<WP> {
  26     // First, partition the where clause into its separate components
  27     let mut params: BTreeMap<_, Vec<_>> = BTreeMap::new();
  28     let mut lifetimes = Vec::new();
  29     let mut equalities = Vec::new();
  30     let mut tybounds = Vec::new();
  31
  32     for clause in clauses {
  33         match clause {
  34             WP::BoundPredicate { ty, bounds } => {
  35                 match ty {
  36                     clean::Generic(s) => params.entry(s).or_default()
  37                                                .extend(bounds),
  38                     t => tybounds.push((t, ty_bounds(bounds))),
  39                 }
  40             }
  41             WP::RegionPredicate { lifetime, bounds } => {
  42                 lifetimes.push((lifetime, bounds));
  43             }
  44             WP::EqPredicate { lhs, rhs } => equalities.push((lhs, rhs)),
  45         }
  46     }
  47
  48     // Simplify the type parameter bounds on all the generics
  49     let mut params = params.into_iter().map(|(k, v)| {
  50         (k, ty_bounds(v))
  51     }).collect::<BTreeMap<_, _>>();
  52
  53     // Look for equality predicates on associated types that can be merged into
  54     // general bound predicates
  55     equalities.retain(|&(ref lhs, ref rhs)| {
  56         let (self_, trait_, name) = match *lhs {
  57             clean::QPath { ref self_type, ref trait_, ref name } => {
  58                 (self_type, trait_, name)
  59             }
  60             _ => return true,
  61         };
  62         let generic = match **self_ {
  63             clean::Generic(ref s) => s,
  64             _ => return true,
  65         };
  66         let trait_did = match **trait_ {
  67             clean::ResolvedPath { did, .. } => did,
  68             _ => return true,
  69         };
  70         let bounds = match params.get_mut(generic) {
  71             Some(bound) => bound,
  72             None => return true,
  73         };
  74         !bounds.iter_mut().any(|b| {
  75             let trait_ref = match *b {
  76                 clean::GenericBound::TraitBound(ref mut tr, _) => tr,
  77                 clean::GenericBound::Outlives(..) => return false,
  78             };
  79             let (did, path) = match trait_ref.trait_ {
  80                 clean::ResolvedPath { did, ref mut path, ..} => (did, path),
  81                 _ => return false,
  82             };
  83             // If this QPath's trait `trait_did` is the same as, or a supertrait
  84             // of, the bound's trait `did` then we can keep going, otherwise
  85             // this is just a plain old equality bound.
  86             if !trait_is_same_or_supertrait(cx, did, trait_did) {
  87                 return false
  88             }
  89             let last = path.segments.last_mut().expect("segments were empty");
  90             match last.args {
  91                 PP::AngleBracketed { ref mut bindings, .. } => {
  92                     bindings.push(clean::TypeBinding {
  93                         name: name.clone(),
  94                         kind: clean::TypeBindingKind::Equality {
  95                             ty: rhs.clone(),
  96                         },
  97                     });
  98                 }
  99                 PP::Parenthesized { ref mut output, .. } => {
 100                     assert!(output.is_none());
 101                     if *rhs != clean::Type::Tuple(Vec::new()) {
 102                         *output = Some(rhs.clone());
 103                     }
 104                 }
 105             };
 106             true
 107         })
 108     });
 109
 110     // And finally, let's reassemble everything
 111     let mut clauses = Vec::new();
 112     clauses.extend(lifetimes.into_iter().map(|(lt, bounds)| {
 113         WP::RegionPredicate { lifetime: lt, bounds: bounds }
 114     }));
 115     clauses.extend(params.into_iter().map(|(k, v)| {
 116         WP::BoundPredicate {
 117             ty: clean::Generic(k),
 118             bounds: v,
 119         }
 120     }));
 121     clauses.extend(tybounds.into_iter().map(|(ty, bounds)| {
 122         WP::BoundPredicate { ty: ty, bounds: bounds }
 123     }));
 124     clauses.extend(equalities.into_iter().map(|(lhs, rhs)| {
 125         WP::EqPredicate { lhs: lhs, rhs: rhs }
 126     }));
 127     clauses
 128 }
 129
 130 pub fn ty_params(mut params: Vec<clean::GenericParamDef>) -> Vec<clean::GenericParamDef> {
 131     for param in &mut params {
 132         match param.kind {
 133             clean::GenericParamDefKind::Type { ref mut bounds, .. } => {
 134                 *bounds = ty_bounds(mem::replace(bounds, Vec::new()));
 135             }
 136             _ => panic!("expected only type parameters"),
 137         }
 138     }
 139     params
 140 }
 141
 142 fn ty_bounds(bounds: Vec<clean::GenericBound>) -> Vec<clean::GenericBound> {
 143     bounds
 144 }
 145
 146 fn trait_is_same_or_supertrait(cx: &DocContext<'_>, child: DefId,
 147                                trait_: DefId) -> bool {
 148     if child == trait_ {
 149         return true
 150     }
 151     let predicates = cx.tcx.super_predicates_of(child);
 152     predicates.predicates.iter().filter_map(|(pred, _)| {
 153         if let ty::Predicate::Trait(ref pred) = *pred {
 154             if pred.skip_binder().trait_ref.self_ty().is_self() {
 155                 Some(pred.def_id())
 156             } else {
 157                 None
 158             }
 159         } else {
 160             None
 161         }
 162     }).any(|did| trait_is_same_or_supertrait(cx, did, trait_))
 163 }