From 98a6cbdba320b106690c01a354f91019020a82d0 Mon Sep 17 00:00:00 2001
From: John Clements <clements@racket-lang.org>
Date: Wed, 29 May 2013 16:21:04 -0700
Subject: [PATCH] comments only

---
 src/libsyntax/ast.rs                | 1 +
 src/libsyntax/ast_util.rs           | 2 ++
 src/libsyntax/ext/expand.rs         | 2 ++
 src/libsyntax/ext/tt/macro_rules.rs | 6 ++++++
 4 files changed, 11 insertions(+)

diff --git a/src/libsyntax/ast.rs b/src/libsyntax/ast.rs
index 8e974cae86e9..cf8fe905d1a3 100644
--- a/src/libsyntax/ast.rs
+++ b/src/libsyntax/ast.rs
@@ -642,6 +642,7 @@ pub enum matcher_ {
     // lo, hi position-in-match-array used:
     match_seq(~[matcher], Option<::parse::token::Token>, bool, uint, uint),
     // parse a Rust NT: name to bind, name of NT, position in match array:
+    // NOTE: 'name of NT' shouldnt really be represented as an ident, should it?
     match_nonterminal(Ident, Ident, uint)
 }
 
diff --git a/src/libsyntax/ast_util.rs b/src/libsyntax/ast_util.rs
index aeca145ea180..4c0ad816afbe 100644
--- a/src/libsyntax/ast_util.rs
+++ b/src/libsyntax/ast_util.rs
@@ -28,6 +28,8 @@ pub fn path_name_i(idents: &[Ident]) -> ~str {
     idents.map(|i| token::interner_get(i.name)).connect("::")
 }
 
+// totally scary function: ignores all but the last element, should have
+// a different name
 pub fn path_to_ident(path: &Path) -> Ident {
     path.segments.last().identifier
 }
diff --git a/src/libsyntax/ext/expand.rs b/src/libsyntax/ext/expand.rs
index 25edcf63faac..039ca36b5561 100644
--- a/src/libsyntax/ext/expand.rs
+++ b/src/libsyntax/ext/expand.rs
@@ -1480,6 +1480,8 @@ mod test {
                 // other, so the result of the whole thing should be "let z_123 = 3; z_123"
                 @"macro_rules! g (($x:ident) => ({macro_rules! f(($y:ident)=>({let $y=3;$x}));f!($x)}))
                    fn a(){g!(z)}"
+                // create a really evil test case where a $x appears inside a binding of $x but *shouldnt*
+                // bind because it was inserted by a different macro....
             ];
         for s in teststrs.iter() {
             // we need regexps to test these!
diff --git a/src/libsyntax/ext/tt/macro_rules.rs b/src/libsyntax/ext/tt/macro_rules.rs
index 50eb03fc96e6..2145e4297e79 100644
--- a/src/libsyntax/ext/tt/macro_rules.rs
+++ b/src/libsyntax/ext/tt/macro_rules.rs
@@ -23,11 +23,15 @@ use parse::token::{get_ident_interner, special_idents, gensym_ident, ident_to_st
 use parse::token::{FAT_ARROW, SEMI, nt_matchers, nt_tt};
 use print;
 
+// this procedure performs the expansion of the
+// macro_rules! macro. It parses the RHS and adds
+// an extension to the current context.
 pub fn add_new_extension(cx: @ExtCtxt,
                          sp: Span,
                          name: Ident,
                          arg: ~[ast::token_tree])
                       -> base::MacResult {
+    // Wrap a matcher_ in a spanned to produce a matcher.
     // these spans won't matter, anyways
     fn ms(m: matcher_) -> matcher {
         Spanned {
@@ -39,11 +43,13 @@ pub fn add_new_extension(cx: @ExtCtxt,
     let lhs_nm =  gensym_ident("lhs");
     let rhs_nm =  gensym_ident("rhs");
 
+    // The pattern that macro_rules matches.
     // The grammar for macro_rules! is:
     // $( $lhs:mtcs => $rhs:tt );+
     // ...quasiquoting this would be nice.
     let argument_gram = ~[
         ms(match_seq(~[
+            // NOTE : probably just use an enum for the NT_name ?
             ms(match_nonterminal(lhs_nm, special_idents::matchers, 0u)),
             ms(match_tok(FAT_ARROW)),
             ms(match_nonterminal(rhs_nm, special_idents::tt, 1u)),