diff --git a/src/libsyntax/parse/common.rs b/src/libsyntax/parse/common.rs
index ae7dd8ff96fce..f353d94894a43 100644
--- a/src/libsyntax/parse/common.rs
+++ b/src/libsyntax/parse/common.rs
@@ -47,17 +47,29 @@ pub fn seq_sep_none() -> SeqSep {
     }
 }
 
+// maps any token back to a string. not necessary if you know it's
+// an identifier....
 pub fn token_to_str(reader: @reader, token: &token::Token) -> ~str {
     token::to_str(reader.interner(), token)
 }
 
 pub impl Parser {
+    // convert a token to a string using self's reader
+    fn token_to_str(&self, token: &token::Token) -> ~str {
+        token::to_str(self.reader.interner(), token)
+    }
+
+    // convert the current token to a string using self's reader
+    fn this_token_to_str(&self) -> ~str {
+        self.token_to_str(self.token)
+    }
+
     fn unexpected_last(&self, t: &token::Token) -> ! {
         self.span_fatal(
             *self.last_span,
             fmt!(
                 "unexpected token: `%s`",
-                token_to_str(self.reader, t)
+                self.token_to_str(t)
             )
         );
     }
@@ -66,7 +78,7 @@ pub impl Parser {
         self.fatal(
             fmt!(
                 "unexpected token: `%s`",
-                token_to_str(self.reader, &copy *self.token)
+                self.this_token_to_str()
             )
         );
     }
@@ -80,8 +92,8 @@ pub impl Parser {
             self.fatal(
                 fmt!(
                     "expected `%s` but found `%s`",
-                    token_to_str(self.reader, t),
-                    token_to_str(self.reader, &copy *self.token)
+                    self.token_to_str(t),
+                    self.this_token_to_str()
                 )
             )
         }
@@ -104,7 +116,7 @@ pub impl Parser {
                 self.fatal(
                     fmt!(
                         "expected ident, found `%s`",
-                        token_to_str(self.reader, &copy *self.token)
+                        self.this_token_to_str()
                     )
                 );
             }
@@ -128,12 +140,15 @@ pub impl Parser {
     // Storing keywords as interned idents instead of strings would be nifty.
 
     // A sanity check that the word we are asking for is a known keyword
+    // NOTE: this could be done statically....
     fn require_keyword(&self, word: &~str) {
         if !self.keywords.contains(word) {
             self.bug(fmt!("unknown keyword: %s", *word));
         }
     }
 
+    // return true when this token represents the given string, and is not
+    // followed immediately by :: .
     fn token_is_word(&self, word: &~str, tok: &token::Token) -> bool {
         match *tok {
             token::IDENT(sid, false) => { *self.id_to_str(sid) == *word }
@@ -150,6 +165,10 @@ pub impl Parser {
         self.token_is_keyword(word, &copy *self.token)
     }
 
+    fn id_is_any_keyword(&self, id: ast::ident) -> bool {
+        self.keywords.contains(self.id_to_str(id))
+    }
+
     fn is_any_keyword(&self, tok: &token::Token) -> bool {
         match *tok {
           token::IDENT(sid, false) => {
@@ -182,7 +201,7 @@ pub impl Parser {
                 fmt!(
                     "expected `%s`, found `%s`",
                     *word,
-                    token_to_str(self.reader, &copy *self.token)
+                    self.this_token_to_str()
                 )
             );
         }
@@ -248,9 +267,9 @@ pub impl Parser {
             );
         } else {
             let mut s: ~str = ~"expected `";
-            s += token_to_str(self.reader, &token::GT);
+            s += self.token_to_str(&token::GT);
             s += ~"`, found `";
-            s += token_to_str(self.reader, &copy *self.token);
+            s += self.this_token_to_str();
             s += ~"`";
             self.fatal(s);
         }
diff --git a/src/libsyntax/parse/parser.rs b/src/libsyntax/parse/parser.rs
index dbdf30b434ff5..c1f781f8570e0 100644
--- a/src/libsyntax/parse/parser.rs
+++ b/src/libsyntax/parse/parser.rs
@@ -66,7 +66,7 @@ use codemap::{span, BytePos, spanned, mk_sp};
 use codemap;
 use parse::attr::parser_attr;
 use parse::classify;
-use parse::common::{seq_sep_none, token_to_str};
+use parse::common::{seq_sep_none};
 use parse::common::{seq_sep_trailing_disallowed, seq_sep_trailing_allowed};
 use parse::lexer::reader;
 use parse::lexer::TokenAndSpan;
@@ -252,8 +252,11 @@ pub fn Parser(sess: @mut ParseSess,
 pub struct Parser {
     sess: @mut ParseSess,
     cfg: crate_cfg,
+    // the current token:
     token: @mut token::Token,
+    // the span of the current token:
     span: @mut span,
+    // the span of the prior token:
     last_span: @mut span,
     buffer: @mut [TokenAndSpan, ..4],
     buffer_start: @mut int,
@@ -499,7 +502,7 @@ pub impl Parser {
             let hi = p.last_span.hi;
             debug!("parse_trait_methods(): trait method signature ends in \
                     `%s`",
-                   token_to_str(p.reader, &copy *p.token));
+                   self.this_token_to_str());
             match *p.token {
               token::SEMI => {
                 p.bump();
@@ -541,7 +544,7 @@ pub impl Parser {
                     p.fatal(
                         fmt!(
                             "expected `;` or `}` but found `%s`",
-                            token_to_str(p.reader, &copy *p.token)
+                            self.this_token_to_str()
                         )
                     );
                 }
@@ -1456,6 +1459,11 @@ pub impl Parser {
     fn parse_token_tree(&self) -> token_tree {
         maybe_whole!(deref self, nt_tt);
 
+        // this is the fall-through for the 'match' below.
+        // invariants: the current token is not a left-delimiter,
+        // not an EOF, and not the desired right-delimiter (if
+        // it were, parse_seq_to_before_end would have prevented
+        // reaching this point.
         fn parse_non_delim_tt_tok(p: &Parser) -> token_tree {
             maybe_whole!(deref p, nt_tt);
             match *p.token {
@@ -1464,7 +1472,7 @@ pub impl Parser {
                 p.fatal(
                     fmt!(
                         "incorrect close delimiter: `%s`",
-                        token_to_str(p.reader, &copy *p.token)
+                        p.this_token_to_str()
                     )
                 );
               }
@@ -1506,18 +1514,17 @@ pub impl Parser {
 
         match *self.token {
             token::EOF => {
-                self.fatal(~"file ended in the middle of a macro invocation");
+                self.fatal(~"file ended with unbalanced delimiters");
             }
             token::LPAREN | token::LBRACE | token::LBRACKET => {
-                // tjc: ??????
-                let ket = token::flip_delimiter(&*self.token);
+                let close_delim = token::flip_delimiter(&*self.token);
                 tt_delim(
                     vec::append(
                         // the open delimiter:
                         ~[parse_any_tt_tok(self)],
                         vec::append(
                             self.parse_seq_to_before_end(
-                                &ket,
+                                &close_delim,
                                 seq_sep_none(),
                                 |p| p.parse_token_tree()
                             ),
@@ -1531,6 +1538,8 @@ pub impl Parser {
         }
     }
 
+    // parse a stream of tokens into a list of token_trees,
+    // up to EOF.
     fn parse_all_token_trees(&self) -> ~[token_tree] {
         let mut tts = ~[];
         while *self.token != token::EOF {
@@ -2053,6 +2062,7 @@ pub impl Parser {
         return e;
     }
 
+    // parse the RHS of a local variable declaration (e.g. '= 14;')
     fn parse_initializer(&self) -> Option<@expr> {
         match *self.token {
           token::EQ => {
@@ -2139,7 +2149,7 @@ pub impl Parser {
                     self.fatal(
                         fmt!(
                             "expected `}`, found `%s`",
-                            token_to_str(self.reader, &copy *self.token)
+                            self.this_token_to_str()
                         )
                     );
                 }
@@ -2407,6 +2417,7 @@ pub impl Parser {
         pat_ident(binding_mode, name, sub)
     }
 
+    // parse a local variable declaration
     fn parse_local(&self, is_mutbl: bool,
                    allow_init: bool) -> @local {
         let lo = self.span.lo;
@@ -2652,7 +2663,7 @@ pub impl Parser {
                                             fmt!(
                                                 "expected `;` or `}` after \
                                                 expression but found `%s`",
-                                                token_to_str(self.reader, &t)
+                                                self.token_to_str(&t)
                                             )
                                         );
                                     }
@@ -2867,7 +2878,7 @@ pub impl Parser {
             self.fatal(
                 fmt!(
                     "expected `self` but found `%s`",
-                    token_to_str(self.reader, &copy *self.token)
+                    self.this_token_to_str()
                 )
             );
         }
@@ -2991,7 +3002,7 @@ pub impl Parser {
                     self.fatal(
                         fmt!(
                             "expected `,` or `)`, found `%s`",
-                            token_to_str(self.reader, &copy *self.token)
+                            self.this_token_to_str()
                         )
                     );
                 }
@@ -3271,7 +3282,7 @@ pub impl Parser {
                 fmt!(
                     "expected `{`, `(`, or `;` after struct name \
                     but found `%s`",
-                    token_to_str(self.reader, &copy *self.token)
+                    self.this_token_to_str()
                 )
             );
         }
@@ -3321,7 +3332,7 @@ pub impl Parser {
                     copy *self.span,
                     fmt!(
                         "expected `;`, `,`, or '}' but found `%s`",
-                        token_to_str(self.reader, &copy *self.token)
+                        self.this_token_to_str()
                     )
                 );
             }
@@ -3423,7 +3434,7 @@ pub impl Parser {
                 self.fatal(
                     fmt!(
                         "expected item but found `%s`",
-                        token_to_str(self.reader, &copy *self.token)
+                        self.this_token_to_str()
                     )
                 );
               }
@@ -3683,7 +3694,7 @@ pub impl Parser {
                 copy *self.span,
                 fmt!(
                     "expected `{` or `mod` but found `%s`",
-                    token_to_str(self.reader, &copy *self.token)
+                    self.this_token_to_str()
                 )
             );
         }
@@ -3696,7 +3707,7 @@ pub impl Parser {
                         copy *self.span,
                         fmt!(
                             "expected foreign module name but found `%s`",
-                            token_to_str(self.reader, &copy *self.token)
+                            self.this_token_to_str()
                         )
                     );
                 }