add some comments about lifetimes etc

src/librustc/ty/util.rs

@@ -621,6 +621,13 @@ pub fn is_static(&self, def_id: DefId) -> Option<hir::Mutability> {
 }
 
 impl<'a, 'tcx> ty::TyS<'tcx> {
+    /// Checks whether values of this type `T` are *moved* or *copied*
+    /// when referenced -- this amounts to a check for whether `T:
+    /// Copy`, but note that we **don't** consider lifetimes when
+    /// doing this check. This means that we may generate MIR which
+    /// does copies even when the type actually doesn't satisfy the
+    /// full requirements for the `Copy` trait (cc #29149) -- this
+    /// winds up being reported as an error during NLL borrow check.
     pub fn moves_by_default(&'tcx self,
                             tcx: TyCtxt<'a, 'tcx, 'tcx>,
                             param_env: ty::ParamEnv<'tcx>,
@@ -629,6 +636,12 @@ pub fn moves_by_default(&'tcx self,
         !tcx.at(span).is_copy_raw(param_env.and(self))
     }
 
+    /// Checks whether values of this type `T` have a size known at
+    /// compile time (i.e., whether `T: Sized`). Lifetimes are ignored
+    /// for the purposes of this check, so it can be an
+    /// over-approximation in generic contexts, where one can have
+    /// strange rules like `<T as Foo<'static>>::Bar: Sized` that
+    /// actually carry lifetime requirements.
     pub fn is_sized(&'tcx self,
                     tcx_at: TyCtxtAt<'a, 'tcx, 'tcx>,
                     param_env: ty::ParamEnv<'tcx>)-> bool
@@ -636,6 +649,11 @@ pub fn is_sized(&'tcx self,
         tcx_at.is_sized_raw(param_env.and(self))
     }
 
+    /// Checks whether values of this type `T` implement the `Freeze`
+    /// trait -- frozen types are those that do not contain a
+    /// `UnsafeCell` anywhere.  This is a language concept used to
+    /// determine how to handle `static` values, the trait itself is
+    /// not exposed to end users.
     pub fn is_freeze(&'tcx self,
                      tcx: TyCtxt<'a, 'tcx, 'tcx>,
                      param_env: ty::ParamEnv<'tcx>,