apply various nits

5 files changed, 46 insertions, 43 deletions

diff --git a/src/librustc/README.md b/src/librustc/README.md
index f2abaa6f957..a5a184ed48c 100644
--- a/src/librustc/README.md
+++ b/src/librustc/README.md
@@ -57,11 +57,12 @@ rustc_trans    rustc_borrowck   ...  rustc_metadata
            syntax_pos  syntax_ext
 ```                    
 
-
-The idea is that `rustc_driver`, at the top of this lattice, basically
-defines the overall control-flow of the compiler. It doesn't have much
-"real code", but instead ties together all of the code defined in the
-other crates and defines the overall flow of execution.
+The `rustc_driver` crate, at the top of this lattice, is effectively
+the "main" function for the rust compiler. It doesn't have much "real
+code", but instead ties together all of the code defined in the other
+crates and defines the overall flow of execution. (As we transition
+more and more to the [query model](ty/maps/README.md), however, the
+"flow" of compilation is becoming less centrally defined.)
 
 At the other extreme, the `rustc` crate defines the common and
 pervasive data structures that all the rest of the compiler uses
diff --git a/src/librustc/hir/README.md b/src/librustc/hir/README.md
index d4f4e48963a..c832a897dee 100644
--- a/src/librustc/hir/README.md
+++ b/src/librustc/hir/README.md
@@ -45,10 +45,10 @@ The other reason to setup the representation this way is for better
 integration with incremental compilation. This way, if you gain access
 to a `&hir::Item` (e.g. for the mod `foo`), you do not immediately
 gain access to the contents of the function `bar()`. Instead, you only
-gain access to the **id** for `bar()`, and you must some function to
-lookup the contents of `bar()` given its id; this gives us a change to
-observe that you accessed the data for `bar()` and record the
-dependency.
+gain access to the **id** for `bar()`, and you must invoke some
+function to lookup the contents of `bar()` given its id; this gives us
+a chance to observe that you accessed the data for `bar()` and record
+the dependency.
 
 ### Identifiers in the HIR
 
@@ -117,7 +117,3 @@ associated with an **owner**, which is typically some kind of item
 (e.g., `|x, y| x + y`). You can use the HIR map to find find the body
 associated with a given def-id (`maybe_body_owned_by()`) or to find
 the owner of a body (`body_owner_def_id()`).
-
-
-
-
diff --git a/src/librustc/hir/mod.rs b/src/librustc/hir/mod.rs
index ea3cdbaad41..c250695f361 100644
--- a/src/librustc/hir/mod.rs
+++ b/src/librustc/hir/mod.rs
@@ -416,6 +416,7 @@ pub type CrateConfig = HirVec<P<MetaItem>>;
 /// The top-level data structure that stores the entire contents of
 /// the crate currently being compiled.
 ///
+/// For more details, see [the module-level README](README.md).
 #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Debug)]
 pub struct Crate {
     pub module: Mod,
@@ -935,9 +936,9 @@ pub struct BodyId {
 /// (which is an expression), but also the argument patterns, since
 /// those are something that the caller doesn't really care about.
 ///
-/// Example:
+/// # Examples
 ///
-/// ```rust
+/// ```
 /// fn foo((x, y): (u32, u32)) -> u32 {
 ///     x + y
 /// }
diff --git a/src/librustc/ty/README.md b/src/librustc/ty/README.md
index 0416be8b9ab..4f63912a1e0 100644
--- a/src/librustc/ty/README.md
+++ b/src/librustc/ty/README.md
@@ -21,7 +21,7 @@ tcx: TyCtxt<'a, 'gcx, 'tcx>
 
 As you can see, the `TyCtxt` type takes three lifetime parameters.
 These lifetimes are perhaps the most complex thing to understand about
-the tcx. During rust compilation, we allocate most of our memory in
+the tcx. During Rust compilation, we allocate most of our memory in
 **arenas**, which are basically pools of memory that get freed all at
 once. When you see a reference with a lifetime like `'tcx` or `'gcx`,
 you know that it refers to arena-allocated data (or data that lives as
@@ -70,18 +70,24 @@ fn maybe_in_inference<'a, 'gcx, 'tcx>(tcx: TyCtxt<'a, 'gcx, 'tcx>, def_id: DefId
 
 ### Allocating and working with types
 
-Rust types are represented using the `ty::Ty<'tcx>` type. This is in fact a simple type alias
-for a reference with `'tcx` lifetime:
+Rust types are represented using the `Ty<'tcx>` defined in the `ty`
+module (not to be confused with the `Ty` struct from [the HIR]). This
+is in fact a simple type alias for a reference with `'tcx` lifetime:
 
 ```rust
 pub type Ty<'tcx> = &'tcx TyS<'tcx>;
 ```
 
-The `TyS` struct defines the actual details of how a type is
-represented. The most interesting part of it is the `sty` field, which
-contains an enum that lets us test what sort of type this is. For
-example, it is very common to see code that tests what sort of type you have
-that looks roughly like so:
+[the HIR]: ../hir/README.md
+
+You can basically ignore the `TyS` struct -- you will basically never
+access it explicitly. We always pass it by reference using the
+`Ty<'tcx>` alias -- the only exception I think is to define inherent
+methods on types. Instances of `TyS` are only ever allocated in one of
+the rustc arenas (never e.g. on the stack).
+
+One common operation on types is to **match** and see what kinds of
+types they are. This is done by doing `match ty.sty`, sort of like this:
 
 ```rust
 fn test_type<'tcx>(ty: Ty<'tcx>) {
@@ -92,10 +98,14 @@ fn test_type<'tcx>(ty: Ty<'tcx>) {
 }
 ```
 
-(Note though that doing such low-level tests on types during inference
-can be risky, as there are may be inference variables and other things
-to consider, or sometimes types are not yet known that will become
-known later.).
+The `sty` field (the origin of this name is unclear to me; perhaps
+structural type?) is of type `TypeVariants<'tcx>`, which is an enum
+definined all of the different kinds of types in the compiler.
+
+> NB: inspecting the `sty` field on types during type inference can be
+> risky, as there are may be inference variables and other things to
+> consider, or sometimes types are not yet known that will become
+> known later.).
 
 To allocate a new type, you can use the various `mk_` methods defined
 on the `tcx`. These have names that correpond mostly to the various kinds
@@ -114,13 +124,13 @@ any inference variables or other "temporary" types, they will be
 allocated in the global arena). However, the lifetime `'tcx` is always
 a safe approximation, so that is what you get back.
 
-NB. Because types are interned, it is possible to compare them for
-equality efficiently using `==` -- however, this is almost never what
-you want to do unless you happen to be hashing and looking for
-duplicates. This is because often in Rust there are multiple ways to
-represent the same type, particularly once inference is involved. If
-you are going to be testing for type equality, you probably need to
-start looking into the inference code to do it right.
+> NB. Because types are interned, it is possible to compare them for
+> equality efficiently using `==` -- however, this is almost never what
+> you want to do unless you happen to be hashing and looking for
+> duplicates. This is because often in Rust there are multiple ways to
+> represent the same type, particularly once inference is involved. If
+> you are going to be testing for type equality, you probably need to
+> start looking into the inference code to do it right.
 
 You can also find various common types in the tcx itself by accessing
 `tcx.types.bool`, `tcx.types.char`, etc (see `CommonTypes` for more).
@@ -153,7 +163,3 @@ In particular, since they are so common, the `Ty` and `TyCtxt` types
 are imported directly. Other types are often referenced with an
 explicit `ty::` prefix (e.g., `ty::TraitRef<'tcx>`). But some modules
 choose to import a larger or smaller set of names explicitly.
-
-
-
-
diff --git a/src/librustc/ty/context.rs b/src/librustc/ty/context.rs
index 6a95c62a303..874bb426dc5 100644
--- a/src/librustc/ty/context.rs
+++ b/src/librustc/ty/context.rs
@@ -793,11 +793,10 @@ impl<'tcx> CommonTypes<'tcx> {
     }
 }
 
-/// The central data structure of the compiler. Keeps track of all the
-/// information that typechecker generates so that so that it can be
-/// reused and doesn't have to be redone later on.
-///
-/// See [the README](README.md) for more deatils.
+/// The central data structure of the compiler. It stores references
+/// to the various **arenas** and also houses the results of the
+/// various **compiler queries** that have been performed. See [the
+/// README](README.md) for more deatils.
 #[derive(Copy, Clone)]
 pub struct TyCtxt<'a, 'gcx: 'a+'tcx, 'tcx: 'a> {
     gcx: &'a GlobalCtxt<'gcx>,