Addressed some of @nrc and @mark-i-m's comments

Author: Michael-F-Bryan

src/appendix-code-index.md

@@ -6,12 +6,17 @@ compiler.
 
 Item            |  Kind    | Short description           | Chapter            | Declaration
 ----------------|----------|-----------------------------|--------------------|-------------------
-`CodeMap` | struct | The CodeMap maps the AST nodes to their source code | [The parser](the-parser.html) | [src/libsyntax/codemap.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/codemap.rs)
-`CompileState` | struct | State that is passed to a callback at each compiler pass | [The Rustc Driver](rustc-driver.html) | [src/librustc_driver/driver.rs](https://github.com/rust-lang/rust/blob/master/src/librustc_driver/driver.rs)
-`ast::Crate` | struct | Syntax-level representation of a parsed crate | | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/ast.rs)
-`hir::Crate` | struct | Top-level data structure representing the crate being compiled | | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/hir/mod.rs)
-`ParseSess` | struct | This struct contains information about a parsing session | [The parser](the-parser.html) | [src/libsyntax/parse/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/mod.rs)
-`StringReader` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser](the-parser.html) |  [src/libsyntax/parse/lexer/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/lexer/mod.rs)
-`Session` | struct | The data associated with a compilation session | [the Parser](the-parser.html), [The Rustc Driver](rustc-driver.html) | [src/librustc/session/mod.html](https://github.com/rust-lang/rust/blob/master/src/librustc/session/mod.rs)
-`TraitDef` | struct | This struct contains a trait's definition with type information | [The `ty` modules](ty.html) |  [src/librustc/ty/trait_def.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/trait_def.rs)
-`TyCtxt<'cx, 'tcx, 'tcx>` | type | The "typing context". This is the central data structure in the compiler. It is the context that you use to perform all manner of queries. | [The `ty` modules](ty.html) | [src/librustc/ty/context.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/context.rs)
+`CodeMap` | struct | The CodeMap maps the AST nodes to their source code | [The parser] | [src/libsyntax/codemap.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/codemap.rs)
+`CompileState` | struct | State that is passed to a callback at each compiler pass | [The Rustc Driver] | [src/librustc_driver/driver.rs](https://github.com/rust-lang/rust/blob/master/src/librustc_driver/driver.rs)
+`ast::Crate` | struct | Syntax-level representation of a parsed crate | [The parser] | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/ast.rs)
+`hir::Crate` | struct | More abstract, compiler-friendly form of a crate's AST | [The Hir] | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/hir/mod.rs)
+`ParseSess` | struct | This struct contains information about a parsing session | [the Parser] | [src/libsyntax/parse/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/mod.rs)
+`Session` | struct | The data associated with a compilation session | [the Parser], [The Rustc Driver] | [src/librustc/session/mod.html](https://github.com/rust-lang/rust/blob/master/src/librustc/session/mod.rs)
+`StringReader` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser] |  [src/libsyntax/parse/lexer/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/lexer/mod.rs)
+`TraitDef` | struct | This struct contains a trait's definition with type information | [The `ty` modules] |  [src/librustc/ty/trait_def.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/trait_def.rs)
+`TyCtxt<'cx, 'tcx, 'tcx>` | type | The "typing context". This is the central data structure in the compiler. It is the context that you use to perform all manner of queries. | [The `ty` modules] | [src/librustc/ty/context.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/context.rs)
+
+[The HIR]: hir.html
+[The parser]: the-parser.html
+[The Rustc Driver]: rustc-driver.html
+[The `ty` modules]: ty.html

src/rustc-driver.md

@@ -8,7 +8,7 @@ managing state such as the [`CodeMap`] \(maps AST nodes to source code),
 stuff). The `rustc_driver` crate also provides external users with a method
 for running code at particular times during the compilation process, allowing
 third parties to effectively use `rustc`'s internals as a library for
-analysing a crate.
+analysing a crate or emulating the compiler in-process (e.g. the RLS).
 
 For those using `rustc` as a library, the `run_compiler()` function is the main
 entrypoint to the compiler. Its main parameters are a list of command-line
@@ -20,10 +20,12 @@ of each phase.
 From `rustc_driver`'s perspective, the main phases of the compiler are:
 
 1. *Parse Input:* Initial crate parsing
-2. *Configure and Expand:* Resolve `#[cfg]` attributes and expand macros
-3. *Run Analysis Passes:* Run the resolution, typechecking, region checking
+2. *Configure and Expand:* Resolve `#[cfg]` attributes, name resolution, and 
+   expand macros
+3. *Run Analysis Passes:* Run trait resolution, typechecking, region checking
    and other miscellaneous analysis passes on the crate
-4. *Translate to LLVM:* Turn the analysed program into executable code
+4. *Translate to LLVM:* Translate to the in-memory form of LLVM IR and turn it 
+   into an executable/object files
 
 The `CompileController` then gives users the ability to inspect the ongoing 
 compilation process
@@ -37,6 +39,9 @@ compilation process
 The `CompileState`'s various `state_after_*()` constructors can be inspected to
 determine what bits of information are available to which callback.
 
+> **Warning:** By its very nature, the internal compiler APIs are always going
+> to be unstable. That said, we do try not to break things unnecessarily.
+
 ## A Note On Lifetimes
 
 The Rust compiler is a fairly large program containing lots of big data