2 files changed, 33 insertions, 0 deletions
diff --git a/src/librustc_middle/ty/codec.rs b/src/librustc_middle/ty/codec.rs
index 270eb42b0c7..291648869fb 100644
--- a/src/librustc_middle/ty/codec.rs
+++ b/src/librustc_middle/ty/codec.rs
@@ -74,6 +74,16 @@ pub trait TyEncoder<'tcx>: Encoder {
     fn encode_alloc_id(&mut self, alloc_id: &AllocId) -> Result<(), Self::Error>;
 }
 
+/// Trait for decoding to a reference.
+///
+/// This is a separate trait from `Decodable` so that we can implement it for
+/// upstream types, such as `FxHashSet`.
+///
+/// The `TyDecodable` derive macro will use this trait for fields that are
+/// references (and don't use a type alias to hide that).
+///
+/// `Decodable` can still be implemented in cases where `Decodable` is required
+/// by a trait bound.
 pub trait RefDecodable<'tcx, D: TyDecoder<'tcx>> {
     fn decode(d: &mut D) -> Result<&'tcx Self, D::Error>;
 }
@@ -301,6 +311,7 @@ macro_rules! impl_decodable_via_ref {
         })*
     }
 }
+
 impl<'tcx, D: TyDecoder<'tcx>> RefDecodable<'tcx, D> for ty::AdtDef {
     fn decode(decoder: &mut D) -> Result<&'tcx Self, D::Error> {
         let def_id = <DefId as Decodable<D>>::decode(decoder)?;
diff --git a/src/librustc_serialize/serialize.rs b/src/librustc_serialize/serialize.rs
index d279954bf91..05c9cf3981b 100644
--- a/src/librustc_serialize/serialize.rs
+++ b/src/librustc_serialize/serialize.rs
@@ -379,10 +379,32 @@ pub trait Decoder {
     fn error(&mut self, err: &str) -> Self::Error;
 }
 
+/// Trait for types that can be serialized
+///
+/// This can be implemented using the `Encodable`, `TyEncodable` and
+/// `MetadataEncodable` macros.
+///
+/// * `Encodable` should be used in crates that don't depend on
+///   `librustc_middle`.
+/// * `TyEncodable` should be used for types that are only serialized in crate
+///   metadata or the incremental cache, except for simple enums.where
+/// * `MetadataEncodable` is used in `rustc_metadata` for types that are only
+///   serialized in crate metadata.
 pub trait Encodable<S: Encoder> {
     fn encode(&self, s: &mut S) -> Result<(), S::Error>;
 }
 
+/// Trait for types that can be deserialized
+///
+/// This can be implemented using the `Decodable`, `TyDecodable` and
+/// `MetadataDecodable` macros.
+///
+/// * `Decodable` should be used in crates that don't depend on
+///   `librustc_middle`.
+/// * `TyDecodable` should be used for types that are only serialized in crate
+///   metadata or the incremental cache, except for simple enums.where
+/// * `MetadataDecodable` is used in `rustc_metadata` for types that are only
+///   serialized in crate metadata.
 pub trait Decodable<D: Decoder>: Sized {
     fn decode(d: &mut D) -> Result<Self, D::Error>;
 }