Start macro expansion chapter

1 files changed, 11 insertions, 0 deletions

diff --git a/src/doc/rustc-dev-guide/src/macro-expansion.md b/src/doc/rustc-dev-guide/src/macro-expansion.md
index 12b95cb6cb0..7ab1c35bc78 100644
--- a/src/doc/rustc-dev-guide/src/macro-expansion.md
+++ b/src/doc/rustc-dev-guide/src/macro-expansion.md
@@ -1 +1,12 @@
 # Macro expansion
+
+Macro expansion happens during parsing. `rustc` has two parsers, in fact: the
+normal Rust parser, and the macro parser. During the parsing phase, the normal
+Rust parser will call into the macro parser when it encounters a macro. The
+macro parser, in turn, may call back out to the Rust parser when it needs to
+bind a metavariable (e.g. `$expr`). There are a few aspects of this system to be
+explained. The code for macro expansion is in `src/libsyntax/ext/tt/`.
+
+TODO: explain parsing of macro definitions
+
+TODO: explain parsing of macro invokations + macro expansion