Add some comments about CrateNum, CrateInfo and .rlink file format

Author: Victor Ding

src/librustc_codegen_llvm/lib.rs

@@ -301,6 +301,7 @@ impl CodegenBackend for LlvmCodegenBackend {
         }
 
         if sess.opts.debugging_opts.no_link {
+            // FIXME: use a binary format to encode the `.rlink` file
             let rlink_data = json::encode(&codegen_results).map_err(|err| {
                 sess.fatal(&format!("failed to encode rlink: {}", err));
             })?;

src/librustc_codegen_ssa/lib.rs

@@ -117,6 +117,12 @@ bitflags::bitflags! {
 }
 
 /// Misc info we load from metadata to persist beyond the tcx.
+/// Note: though `CrateNum` is only meaningful within the same tcx, information within `CrateInfo`
+/// is self-contained. `CrateNum` can be viewed as a unique identifier within a `CrateInfo`, where
+/// `used_crate_source` contains all `CrateSource` of the dependents, and maintains a mapping from
+/// identifiers (`CrateNum`) to `CrateSource`. The other fields map `CrateNum` to the crate's own
+/// additional properties, so that effectively we can retrieve each dependent crate's `CrateSource`
+/// and the corresponding properties without referencing information outside of a `CrateInfo`.
 #[derive(Debug, RustcEncodable, RustcDecodable)]
 pub struct CrateInfo {
     pub panic_runtime: Option<CrateNum>,

src/librustc_hir/def_id.rs

@@ -87,6 +87,8 @@ impl fmt::Display for CrateNum {
     }
 }
 
+/// As a local identifier, a `CrateNum` is only meaningful within its context, e.g. within a tcx.
+/// Therefore, make sure to include the context when encode a `CrateNum`.
 impl rustc_serialize::UseSpecializedEncodable for CrateNum {
     fn default_encode<E: Encoder>(&self, e: &mut E) -> Result<(), E::Error> {
         e.emit_u32(self.as_u32())