auto merge of rust-lang#10600 : ktt3ja/rust/add-doc, r=huonw

I received a lot of helpful explanations when I was going through rustc's middle-end code. I document some of them here.

src/librustc/middle/pat_util.rs

@@ -70,6 +70,8 @@ pub fn pat_is_binding_or_wild(dm: resolve::DefMap, pat: @Pat) -> bool {
     }
 }
 
+/// Call `it` on every "binding" in a pattern, e.g., on `a` in
+/// `match foo() { Some(a) => (), None => () }`
 pub fn pat_bindings(dm: resolve::DefMap,
                     pat: @Pat,
                     it: |BindingMode, NodeId, Span, &Path|) {

src/librustc/middle/ty.rs

@@ -259,6 +259,9 @@ pub enum AutoRef {
 
 pub type ctxt = @ctxt_;
 
+/// The data structure to keep 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.
 struct ctxt_ {
     diag: @mut syntax::diagnostic::span_handler,
     interner: @mut HashMap<intern_key, ~t_box_>,
@@ -296,6 +299,8 @@ struct ctxt_ {
     trait_refs: @mut HashMap<NodeId, @TraitRef>,
     trait_defs: @mut HashMap<DefId, @TraitDef>,
 
+    /// Despite its name, `items` does not only map NodeId to an item but
+    /// also to expr/stmt/local/arg/etc
     items: ast_map::map,
     intrinsic_defs: @mut HashMap<ast::DefId, t>,
     freevars: freevars::freevar_map,

src/libsyntax/ast.rs

@@ -173,6 +173,8 @@ pub struct DefId {
     node: NodeId,
 }
 
+/// Item definitions in the currently-compiled crate would have the CrateNum
+/// LOCAL_CRATE in their DefId.
 pub static LOCAL_CRATE: CrateNum = 0;
 pub static CRATE_NODE_ID: NodeId = 0;
 
@@ -244,6 +246,10 @@ pub enum Def {
               @Def,     // closed over def
               NodeId,  // expr node that creates the closure
               NodeId), // id for the block/body of the closure expr
+
+    /// Note that if it's a tuple struct's definition, the node id
+    /// of the DefId refers to the struct_def.ctor_id (whereas normally it
+    /// refers to the item definition's id).
     DefStruct(DefId),
     DefTyParamBinder(NodeId), /* struct, impl or trait with ty params */
     DefRegion(NodeId),
@@ -451,6 +457,7 @@ pub enum Stmt_ {
 
 // FIXME (pending discussion of #1697, #2178...): local should really be
 // a refinement on pat.
+/// Local represents a `let` statement, e.g., `let <pat>:<ty> = <expr>;`
 #[deriving(Eq, Encodable, Decodable,IterBytes)]
 pub struct Local {
     ty: Ty,
@@ -553,6 +560,10 @@ pub enum Expr_ {
     ExprAssignOp(NodeId, BinOp, @Expr, @Expr),
     ExprField(@Expr, Ident, ~[Ty]),
     ExprIndex(NodeId, @Expr, @Expr),
+
+    /// Expression that looks like a "name". For example,
+    /// `std::vec::from_elem::<uint>` is an ExprPath that's the "name" part
+    /// of a function call.
     ExprPath(Path),
 
     /// The special identifier `self`.

src/libsyntax/ast_map.rs

@@ -111,12 +111,18 @@ pub enum ast_node {
     node_trait_method(@trait_method, DefId /* trait did */,
                       @path /* path to the trait */),
     node_method(@method, DefId /* impl did */, @path /* path to the impl */),
+
+    /// node_variant represents a variant of an enum, e.g., for
+    /// `enum A { B, C, D }`, there would be a node_item for `A`, and a
+    /// node_variant item for each of `B`, `C`, and `D`.
     node_variant(variant, @item, @path),
     node_expr(@Expr),
     node_stmt(@Stmt),
     node_arg(@Pat),
     node_local(Ident),
     node_block(Block),
+
+    /// node_struct_ctor represents a tuple struct.
     node_struct_ctor(@struct_def, @item, @path),
     node_callee_scope(@Expr)
 }