Update README files

src/README

@@ -4,6 +4,10 @@ Source layout:
 
 comp/              The self-hosted compiler
 
+lib/               The standard library
+
+rustllvm/          LLVM support code
+
 rt/                The runtime system
 rt/rust_*.cpp      - The majority of the runtime services
 rt/isaac           - The PRNG used for pseudo-random choices in the runtime
@@ -11,7 +15,7 @@ rt/bigint          - The bigint library used for the 'big' type
 rt/uthash          - Small hashtable-and-list library for C, used in runtime
 rt/{sync,util}     - Small utility classes for the runtime.
 
-test/              Testsuite (for both bootstrap and self-hosted)
+test/              Testsuite
 test/compile-fail  - Tests that should fail to compile
 test/run-fail      - Tests that should compile, run and fail
 test/run-pass      - Tests that should compile, run and succeed

src/comp/README

@@ -2,8 +2,9 @@ An informal guide to reading and working on the rustc compiler.
 ==================================================================
 
 If you wish to expand on this document, or have one of the
-slightly-more-familiar authors add anything else to it, please get in touch or
+slightly-more-familiar authors add anything else to it, please get in
-file a bug. Your concerns are probably the same as someone else's.
+touch or file a bug. Your concerns are probably the same as someone
+else's.
 
 
 High-level concepts
@@ -13,65 +14,63 @@ Rustc consists of the following subdirectories:
 
 front/    - front-end: lexer, parser, AST.
 middle/   - middle-end: resolving, typechecking, translating
+back/     - back-end: linking and ABI
 driver/   - command-line processing, main() entrypoint
 util/     - ubiquitous types and helper functions
 lib/      - bindings to LLVM
+pretty/   - pretty-printing
 
-The entry-point for the compiler is main() in driver/rustc.rs, and this file
+The entry-point for the compiler is main() in driver/rustc.rs, and
-sequences the various parts together.
+this file sequences the various parts together.
 
 
 The 3 central data structures:
 ------------------------------
 
-#1: front/ast.rs defines the AST. The AST is treated as immutable after
+#1: front/ast.rs defines the AST. The AST is treated as immutable
-    parsing despite containing some mutable types (hashtables and such).
+    after parsing despite containing some mutable types (hashtables
-    There are three interesting details to know about this structure:
+    and such).  There are three interesting details to know about this
+    structure:
 
-      - Many -- though not all -- nodes within this data structure are wrapped
+      - Many -- though not all -- nodes within this data structure are
-        in the type spanned[T], meaning that the front-end has marked the
+        wrapped in the type spanned[T], meaning that the front-end has
-        input coordinates of that node. The member .node is the data itself,
+        marked the input coordinates of that node. The member .node is
-        the member .span is the input location (file, line, column; both low
+        the data itself, the member .span is the input location (file,
-        and high).
+        line, column; both low and high).
 
-      - Many other nodes within this data structure carry a def_id. These
+      - Many other nodes within this data structure carry a
-        nodes represent the 'target' of some name reference elsewhere in the
+        def_id. These nodes represent the 'target' of some name
-        tree. When the AST is resolved, by middle/resolve.rs, all names wind
+        reference elsewhere in the tree. When the AST is resolved, by
-        up acquiring a def that they point to. So anything that can be
+        middle/resolve.rs, all names wind up acquiring a def that they
-        pointed-to by a name winds up with a def_id.
+        point to. So anything that can be pointed-to by a name winds
+        up with a def_id.
 
-      - Many nodes carry an additional type 'ann', for annotations. These
+#2: middle/ty.rs defines the datatype sty.  This is the type that
-        nodes are those that later stages of the middle-end add information
+    represents types after they have been resolved and normalized by
-        to, augmenting the basic structure of the tree. Currently that
+    the middle-end. The typeck phase converts every ast type to a
-        includes the calculated type of any node that has a type; it will also
+    ty::sty, and the latter is used to drive later phases of
-        likely include typestates, layers and effects, when such things are
+    compilation.  Most variants in the ast::ty tag have a
-        calculated.
+    corresponding variant in the ty::sty tag.
 
-#2: middle/ty.rs defines the datatype ty.t, with its central member ty.struct.
+#3: lib/llvm.rs defines the exported types ValueRef, TypeRef,
-    This is the type that represents types after they have been resolved and
+    BasicBlockRef, and several others. Each of these is an opaque
-    normalized by the middle-end. The typeck phase converts every ast type to
+    pointer to an LLVM type, manipulated through the lib.llvm
-    a ty.t, and the latter is used to drive later phases of compilation.  Most
+    interface.
-    variants in the ast.ty tag have a corresponding variant in the ty.struct
-    tag.
-
-#3: lib/llvm.rs defines the exported types ValueRef, TypeRef, BasicBlockRef,
-    and several others. Each of these is an opaque pointer to an LLVM type,
-    manipulated through the lib.llvm interface.
 
 
 Control and information flow within the compiler:
 -------------------------------------------------
 
-- main() in driver/rustc.rs assumes control on startup. Options are parsed,
+- main() in driver/rustc.rs assumes control on startup. Options are
-  platform is detected, etc.
+  parsed, platform is detected, etc.
 
 - front/parser.rs is driven over the input files.
 
-- Multiple middle-end passes (middle/resolve.rs, middle/typeck.rs) are run
+- Multiple middle-end passes (middle/resolve.rs, middle/typeck.rs) are
-  over the resulting AST. Each pass produces a new AST with some number of
+  run over the resulting AST. Each pass generates new information
-  annotations or modifications.
+  about the AST which is stored in various side data structures.
 
 - Finally middle/trans.rs is applied to the AST, which performs a
-  type-directed translation to LLVM-ese. When it's finished synthesizing LLVM
+  type-directed translation to LLVM-ese. When it's finished
-  values, rustc asks LLVM to write them out as an executable, on which the
+  synthesizing LLVM values, rustc asks LLVM to write them out in some
-  normal LLVM pipeline (opt, llc, as) was run.
+  form (.bc, .o) and possibly run the system linker.