Try to write some basic docs.

Author: nikomatsakis

src/librustc/middle/infer/bivariate.rs

@@ -8,6 +8,23 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Applies the "bivariance relationship" to two types and/or regions.
+//! If (A,B) are bivariant then either A <: B or B <: A. It occurs
+//! when type/lifetime parameters are unconstrained. Usually this is
+//! an error, but we permit it in the specific case where a type
+//! parameter is constrained in a where-clause via an associated type.
+//!
+//! There are several ways one could implement bivariance. You could
+//! just do nothing at all, for example, or you could fully verify
+//! that one of the two subtyping relationships hold. We choose to
+//! thread a middle line: we relate types up to regions, but ignore
+//! all region relationships.
+//!
+//! At one point, handling bivariance in this fashion was necessary
+//! for inference, but I'm actually not sure if that is true anymore.
+//! In particular, it might be enough to say (A,B) are bivariant for
+//! all (A,B).
+
 use middle::ty::{BuiltinBounds};
 use middle::ty::{self, Ty};
 use middle::ty::TyVar;

src/librustc/middle/infer/sub.rs

@@ -39,7 +39,6 @@ impl<'f, 'tcx> Combine<'tcx> for Sub<'f, 'tcx> {
     fn tys_with_variance(&self, v: ty::Variance, a: Ty<'tcx>, b: Ty<'tcx>)
                          -> cres<'tcx, Ty<'tcx>>
     {
-        // Once we're equating, it doesn't matter what the variance is.
         match v {
             ty::Invariant => self.equate().tys(a, b),
             ty::Covariant => self.tys(a, b),

src/librustc/middle/traits/select.rs

@@ -803,8 +803,9 @@ impl<'cx, 'tcx> SelectionContext<'cx, 'tcx> {
             ambiguous: false
         };
 
-        // Check for the `PhantomFn` trait. This is really just a special annotation that
-        // *always* be considered to match, no matter what the type parameters etc.
+        // Check for the `PhantomFn` trait. This is really just a
+        // special annotation that is *always* considered to match, no
+        // matter what the type parameters are etc.
         if self.tcx().lang_items.phantom_fn() == Some(obligation.predicate.def_id()) {
             candidates.vec.push(PhantomFnCandidate);
             return Ok(candidates);