macros: rename some sections, cover macro expansion (WIP)

diff --git a/examples/staging/macros/arguments/designators.rs b/examples/staging/macros/arguments/designators.rs
index 0b88855..9e9f78a 100644
--- a/examples/staging/macros/arguments/designators.rs
+++ b/examples/staging/macros/arguments/designators.rs

@@ -1,28 +1,28 @@
 #![feature(macro_rules)]
 
 macro_rules! create_function {
-    // this macro takes an argument of "type" `ident`
-    // the `ident` designator is used for variable/function names
+    // This macro takes an argument of "type" `ident`
+    // The `ident` designator is used for variable/function names
     ($func_name:ident) => {
-        // this macro creates a function with name `$func_name`
+        // This macro creates a function with name `$func_name`
         fn $func_name() {
-            // the stringify! macro converts an `ident` into a string
-            println!("You called {}()",
-                     stringify!($func_name))
+            // The `stringify!` macro converts an `ident` into a string
+            println!("You called {}()", stringify!($func_name))
         }
     }
 }
 
 create_function!(foo)
 create_function!(bar)
+// Designators provide type safety in macros
+//create_function!(0)
+// TODO ^ Try uncommenting this line
 
 macro_rules! print_result {
-    // the `expr` designator is used for expressions
+    // The `expr` designator is used for expressions
     ($expression:expr) => {
-        // stringify! will convert the expression *as it is* into a string
-        println!("{} = {}",
-                 stringify!($expression),
-                 $expression)
+        // `stringify!` will convert the expression *as it is* into a string
+        println!("{} = {}", stringify!($expression), $expression)
     }
 }
 
@@ -32,7 +32,7 @@
 
     print_result!(1u + 1);
 
-    // remember that blocks are expressions
+    // Remember that blocks are expressions too
     print_result!({
         let x = 1u;
 

diff --git a/examples/staging/macros/arguments/input.md b/examples/staging/macros/arguments/input.md
index 93f7efa..ba2e8e3 100644
--- a/examples/staging/macros/arguments/input.md
+++ b/examples/staging/macros/arguments/input.md

@@ -9,10 +9,10 @@
 * `expr` is used for expressions
 * `ident` is used for variable/function names
 * `item`
-* `matchers` (lhs of the => in macro rules)
+* `matchers`
 * `pat`
 * `path`
 * `stmt`
-* `tt` (*token tree*) is used for operators and tokens
+* `tt` (*token tree*) is used for operators (`+`, `-`, etc)
 * `ty` (*type*)
 

diff --git a/examples/staging/macros/arity/input.md b/examples/staging/macros/arity/input.md
new file mode 100644
index 0000000..f8c954f
--- /dev/null
+++ b/examples/staging/macros/arity/input.md

@@ -0,0 +1,15 @@
+Macros can have different implementations depending on their arity (number of
+arguments), this can be used to implement some form of function overloading.
+Here we implement a macro similar to Python's overloaded
+[range](https://docs.python.org/3/library/stdtypes.html?highlight=range#range)
+function:
+
+```rust
+// Here is how it should work
+range!(10i)       // Returns 0..9
+range!(3i, 10)    // Returns 3..9
+range!(3i, 10, 2) // Returns 3, 5, 7, 9 (3..9 in increments of 2)
+```
+
+{range.play}
+

diff --git a/examples/staging/macros/arity/range.rs b/examples/staging/macros/arity/range.rs
new file mode 100644
index 0000000..98a7025
--- /dev/null
+++ b/examples/staging/macros/arity/range.rs

@@ -0,0 +1,32 @@
+#![feature(macro_rules)]
+
+use std::iter::range_step;
+
+// `macro_rules` behaves like a `match` expression
+macro_rules! range (
+    // The left side of the fat arrow is the `pattern` side, and the right side
+    // is the `expansion` side
+    ($end:expr) => {
+        range(0, $end)
+    };
+    // The macro can have a different expansion for each arity
+    ($start:expr, $end:expr) => {
+        range($start, $end)
+    };
+    // ^ Each pattern-match arm must be terminated by a semicolon
+    ($start:expr, $end:expr, $step:expr) => {
+        range_step($start, $end, $step)
+    };
+    // The semicolon on the last arm is optional (is a trailing semicolon)
+)
+
+fn main() {
+    for i in range!(10i) { print!("{}", i) }
+    println!("");
+
+    for i in range!(3i, 10) { print!("{}", i) }
+    println!("");
+
+    for i in range!(3i, 10, 2) { print!("{}", i) }
+}
+

diff --git a/examples/staging/macros/test_suite/dry.rs b/examples/staging/macros/dry/dry.rs
similarity index 100%
rename from examples/staging/macros/test_suite/dry.rs
rename to examples/staging/macros/dry/dry.rs


diff --git a/examples/staging/macros/test_suite/input.md b/examples/staging/macros/dry/input.md
similarity index 100%
rename from examples/staging/macros/test_suite/input.md
rename to examples/staging/macros/dry/input.md


diff --git a/examples/staging/macros/expand/input.md b/examples/staging/macros/expand/input.md
new file mode 100644
index 0000000..0b967d1
--- /dev/null
+++ b/examples/staging/macros/expand/input.md

@@ -0,0 +1,30 @@
+You can check the expansion of any macro by running the
+`rustc --pretty expanded` command over your source file.
+
+Let's see what the `vec!` macro expands to:
+
+{vec.rs}
+
+``` rust
+$ rustc --pretty expanded vec.rs
+#![feature(phase)]
+#![no_std]
+#![feature(globs)]
+#[phase(plugin, link)]
+extern crate std;
+extern crate native;
+use std::prelude::*;
+fn main() {
+    let v1 =
+        { let mut _temp = ::std::vec::Vec::new(); _temp.push(1u); _temp };
+    let v2 =
+        {
+            let mut _temp = ::std::vec::Vec::new();
+            _temp.push(1u);
+            _temp.push(2);
+            _temp
+        };
+}
+```
+
+Soon you'll learn how to define macros that work like this one!

diff --git a/examples/staging/macros/expand/vec.rs b/examples/staging/macros/expand/vec.rs
new file mode 100644
index 0000000..21f5438
--- /dev/null
+++ b/examples/staging/macros/expand/vec.rs

@@ -0,0 +1,4 @@
+fn main() {
+    let v1 = vec!(1u);
+    let v2 = vec!(1u, 2);
+}

diff --git a/examples/staging/macros/input.md b/examples/staging/macros/input.md
index 819a4a5..5d5b030 100644
--- a/examples/staging/macros/input.md
+++ b/examples/staging/macros/input.md

@@ -3,7 +3,7 @@
 ends with a bang `!`, but instead of generating a function call, macros are
 expanded into source code that gets compiled with the rest of the program.
 
-Macros are created using the `macro_rules!` macro.
+Macros are defined using the `macro_rules!` macro.
 
 {simple.play}
 

diff --git a/examples/staging/macros/repetition/input.md b/examples/staging/macros/repetition/input.md
index bcc71bb..f1cce1d 100644
--- a/examples/staging/macros/repetition/input.md
+++ b/examples/staging/macros/repetition/input.md

@@ -1,51 +1,32 @@
-Macros can also match and return repeated patterns. This is similar but
-different from a regex. `$($x:expr),+` is a matching example. It uses the
-`$()` grouping operator to mark `x` as repeatable. `+` or `*` denotes
-repetition amount; one or more and zero or more respectively. `,`
-is the only separator token available.
+Macros can be defined to handle indefinite arity (any number of arguments).
+This can be accomplished using the *repetition* syntax and the `+`
+and `*` operators. This is what the syntax looks like:
 
-```rust
-// The separator only checks separation; this is
-// not a regex.
-$($x:expr),+ // matches `1, 2, 3` but not `1, 2,`
-```
+On the pattern side:
 
-When returned, it uses a similar notation: `$($x:expr),+` => `$($x),+`
-however, a returned list will not be re-expanded whereas, matching
-will find the whole thing.
+* `($($x:expr),+)`: matches a list (with at least one element) of `expr`s
+  separated by commas. Examples: `('a', 'b')` and `(1 + 2, 3 * 4, 5 - 6)`
 
-```rust
-#![feature(macro_rules)]
+* `($($y:ident),*)`: matches a list of `ident`s separated by commas, but also
+  handles the zero arity case. Examples: `()` and `(foo, bar)`
 
-macro_rules! echo_broken {
-    // Attempt to match and return with one compact expression
-    ($($x:expr),+) => { $($x),+ };
-}
+* Neither of these two patterns will match a list that has a trailing comma. To
+  allow trailing commas, you can use this pattern: `($($z:expr),+,)`
 
-macro_rules! echo_works {
-    ($x:expr) => { $x }; // one element list
-    // $x is the first element. `$($y:expr),+` is the tail
-    ($x:expr, $($y:expr),+) => {
-        // pass the tail to `echo_works` so it can be expanded
-        ($x, echo_works!($($y),+))
-    };
-}
+On the expansion side:
 
-fn main() {
-    println!("{}", echo_broken!(1u)); // Works for single elements
+* `[$($x),+]`: will expand the input arguments (the `$x`s) into an array.
+  Following the previous example: `['a', 'b']` and `[1 + 2, 3 * 4, 5 - 6]`
 
-    // Errors: `,` ignored. A list is never re-expanded so when
-    // the `,` is reached, the rest of the line is ignored.
-    // Rust does not allow incomplete expansion, so it errors. To
-    // handle this, recursion is needed.
-    //println!("{}", echo_broken!(1u, 2u));
+For our example, we'll make a `min!` macro that can take any number of
+arguments and will return the smallest one. Under the hood it will use the
+`min` function that compares *two* arguments.
 
-    println!("{}", echo_works!(1u));
-    // Would like it flat but it nests the results...
-    println!("{}", echo_works!(1u, 2u, 3u, 4u, 5u, 6u));
-}
-```
-
-Another example making a min macro:
 {repeat.play}
 
+If you check the expansion you'll see this expression in the place of the last
+macro:
+
+``` rust
+std::cmp::min(5u, std::cmp::min(2u * 3, 4u))
+```

diff --git a/examples/staging/macros/repetition/repeat.rs b/examples/staging/macros/repetition/repeat.rs
index dbe6258..a9a1780 100644
--- a/examples/staging/macros/repetition/repeat.rs
+++ b/examples/staging/macros/repetition/repeat.rs

@@ -1,16 +1,16 @@
 #![feature(macro_rules)]
 
-// min! will calculate the minimum of any number of arguments
+// It's common to use recursion to handle indefinite arity
 macro_rules! min {
     // base case
     ($x:expr) => {
         $x
     };
-    // `$x` followed by at least one `$y,`
+    // `$x` followed by at least another `expr`
     ($x:expr, $($y:expr),+) => {
-        // call min! on the tail `$y`
+        // Recursion! Call `min!` on the tail
         std::cmp::min($x, min!($($y),+))
-    }
+    };
 }
 
 fn main() {

diff --git a/examples/staging/macros/separators/input.md b/examples/staging/macros/separators/input.md
index 82fb09b..8644cdd 100644
--- a/examples/staging/macros/separators/input.md
+++ b/examples/staging/macros/separators/input.md

@@ -1,4 +1,20 @@
-Macros can be overloaded to accept different combinations of arguments.
+So far we have been using a comma to separate the arguments fed into a macro,
+but macros are more flexible than that! You are free to use symbols or words to
+separate the input arguments of the macro.
 
-{overload.play}
+Let's create a sugary macro to initialize hash maps:
 
+{separators.play}
+
+The expansion of the `map!` macro looks like this:
+
+``` rust
+let alphabet =
+        {
+            let mut _temp = std::collections::HashMap::new();
+            _temp.insert('a', "apple");
+            _temp.insert('b', "banana");
+            _temp.insert('c', "carrot");
+            _temp
+        };
+```

diff --git a/examples/staging/macros/separators/overload.rs b/examples/staging/macros/separators/overload.rs
deleted file mode 100644
index e1e04b2..0000000
--- a/examples/staging/macros/separators/overload.rs
+++ /dev/null

@@ -1,25 +0,0 @@
-#![feature(macro_rules)]
-
-// macro_rules! is similar to a match block
-macro_rules! test {
-    // the arguments don't need to be separated by a comma
-    // any template can be used
-    ($left:expr and $right:expr) => {
-        println!("{} and {} is {}",
-                 stringify!($left),
-                 stringify!($right),
-                 $left && $right)
-    };
-    // ^ each arm must be ended with a semicolon
-    ($left:expr or $right:expr) => {
-        println!("{} or {} is {}",
-                 stringify!($left),
-                 stringify!($right),
-                 $left || $right)
-    };
-}
-
-fn main() {
-    test!(1i + 1 == 2i and 2i * 2 == 4i);
-    test!(true or false);
-}

diff --git a/examples/staging/macros/separators/separators.rs b/examples/staging/macros/separators/separators.rs
new file mode 100644
index 0000000..3d38c2e
--- /dev/null
+++ b/examples/staging/macros/separators/separators.rs

@@ -0,0 +1,26 @@
+#![feature(macro_rules)]
+
+macro_rules! map {
+    ($($key:expr => $value:expr),*) => ({
+        let mut _temp = std::collections::HashMap::new();
+
+        $(_temp.insert($key, $value);)*
+
+        _temp
+    });
+    // Handle trailing commas
+    ($($key:expr => $value:expr),+,) => (
+        map!($($key => $value),+)
+    );
+}
+
+fn main() {
+    let alphabet = map! {
+        'a' => "apple",
+        'b' => "banana",
+        'c' => "carrot",
+    };
+
+    println!("{}", alphabet);
+}
+

diff --git a/examples/staging/macros/simple.rs b/examples/staging/macros/simple.rs
index 648bc07..ac8fb9b 100644
--- a/examples/staging/macros/simple.rs
+++ b/examples/staging/macros/simple.rs

@@ -1,16 +1,16 @@
-// macros are behind a feature gate
+// Macros are behind a "feature gate", because they are considered experimental
 #![feature(macro_rules)]
 
 // This is the simplest macro, `say_hello` is the name of the macro
 macro_rules! say_hello {
     // `()` indicates that the macro takes no argument
     () => {
-        // the macro will expand into the contents of this block
+        // The macro will expand into the contents of this block
         println!("Hello!");
     }
 }
 
 fn main() {
-    // this call will expand into `println!("Hello");`
-    say_hello!()
+    // This call will expand into `println!("Hello");`
+    say_hello!();
 }

diff --git a/examples/staging/macros/variable_args/input.md b/examples/staging/macros/variable_args/input.md
deleted file mode 100644
index d8d0b20..0000000
--- a/examples/staging/macros/variable_args/input.md
+++ /dev/null

@@ -1,13 +0,0 @@
-Variadic (variable number of arguments) functions can be implemented via
-macros. Here we implement a macro similar to Python's overloaded
-[range](https://docs.python.org/3/tutorial/controlflow.html#the-range-function) function:
-
-```rust
-// Here is how it should work
-range!(10i)       // Returns 0..9
-range!(3i, 10)    // Returns 3..9
-range!(3i, 10, 2) // Returns 3, 5, 7, 9 (3..9 in increments of 2)
-```
-
-{range.play}
-

diff --git a/examples/staging/macros/variable_args/range.rs b/examples/staging/macros/variable_args/range.rs
deleted file mode 100644
index 5eb4205..0000000
--- a/examples/staging/macros/variable_args/range.rs
+++ /dev/null

@@ -1,28 +0,0 @@
-#![feature(macro_rules)]
-
-use std::iter::range_step;
-
-// range! will take up to 3 inputs and call range
-// function depending on inputs
-macro_rules! range (
-    ($end:expr) => {
-        range(0, $end)
-    };
-    ($start:expr, $end:expr) => {
-        range($start, $end)
-    };
-    ($start:expr, $end:expr, $step:expr) => {
-        range_step($start, $end, $step)
-    };
-)
-
-fn main() {
-    for i in range!(10i) { print!("{}", i) }
-    println!("");
-
-    for i in range!(3i, 10) { print!("{}", i) }
-    println!("");
-
-    for i in range!(3i, 10, 2) { print!("{}", i) }
-}
-

diff --git a/examples/structure.json b/examples/structure.json
index 207823a..6247e8a 100644
--- a/examples/structure.json
+++ b/examples/structure.json

@@ -104,11 +104,13 @@
     { "id": "bench", "title": "Benchmarking", "children": null  },
     { "id": "ffi", "title": "Foreign Function Interface", "children": null  },
     { "id": "macros", "title": "macro_rules!", "children": [
-      { "id": "arguments", "title": "Arguments and designators", "children": null },
-      { "id": "variable_args", "title": "Variadic macros", "children": null },
-      { "id": "separators", "title": "Variable separator options", "children": null },
-      { "id": "repetition", "title": "Repetition and expansion", "children": null },
-      { "id": "test_suite", "title": "Generating generic test suite implementations", "children": null }
+      { "id": "expand", "title": "Expansion", "children": null },
+      { "id": "arguments", "title": "Designators", "children": null },
+      { "id": "arity", "title": "Arity", "children": null },
+      { "id": "repetition", "title": "Repetition", "children": null },
+      { "id": "separators", "title": "Separators", "children": null },
+      { "id": "dry", "title": "DRY", "children": null },
+      { "id": "export", "title": "Export", "children": null }
   ] },
     { "id": "rand", "title": "Random", "children": null  },
     { "id": "simd", "title": "SIMD", "children": null  },