Add some comments to kind.rs and last_use.rs

Author: marijnh

src/comp/middle/kind.rs

@@ -3,6 +3,21 @@ import syntax::{visit, ast_util};
 import syntax::ast::*;
 import syntax::codemap::span;
 
+// Kind analysis pass. There are three kinds:
+//
+//  sendable: scalar types, and unique types containing only sendable types
+//  copyable: boxes, objects, closures, and uniques containing copyable types
+//  noncopyable: resources, or unique types containing resources
+//
+// This pass ensures that type parameters are only instantiated with types
+// whose kinds are equal or less general than the way the type parameter was
+// annotated (with the `send` or `copy` keyword).
+//
+// It also verifies that noncopyable kinds are not copied. Sendability is not
+// applied, since none of our language primitives send. Instead, the sending
+// primitives in the stdlib are explicitly annotated to only take sendable
+// types.
+
 fn kind_to_str(k: kind) -> str {
     alt k {
       kind_sendable. { "sendable" }

src/comp/middle/last_use.rs

@@ -3,6 +3,24 @@ import syntax::ast::*;
 import std::list::{list, nil, cons, tail};
 import std::{vec, list, option};
 
+// Last use analysis pass.
+//
+// Finds the last read of each value stored in a local variable or
+// callee-owned argument (arguments with by-move or by-copy passing
+// style). This is a limited form of liveness analysis, peformed
+// (perhaps foolishly) directly on the AST.
+//
+// The algorithm walks the AST, keeping a set of (def, last_use)
+// pairs. When the function is exited, or the local is overwritten,
+// the current set of last uses is marked with 'true' in a table.
+// Other branches may later overwrite them with 'false' again, since
+// they may find a use coming after them. (Marking an expression as a
+// last use is only done if it has not already been marked with
+// 'false'.)
+//
+// Some complexity is added to deal with joining control flow branches
+// (by `break` or conditionals), and for handling loops.
+
 // Marks expr_paths that are last uses.
 type last_uses = std::map::hashmap<node_id, ()>;