Add some comments about token spans.

Information that took me a while to work out.

Author: nnethercote

compiler/rustc_ast/src/token.rs

@@ -333,6 +333,10 @@ pub enum TokenKind {
     /// - It prevents `Token` from implementing `Copy`.
     /// It adds complexity and likely slows things down. Please don't add new
     /// occurrences of this token kind!
+    ///
+    /// Note: the span here is for the LHS macro parameter declaration, e.g.
+    /// `$id:ident`, `$t:ty`. (The span covers the metavariable name, the `:`,
+    /// and the fragment specifier kind.)
     Interpolated(Lrc<(Nonterminal, Span)>),
 
     /// A doc comment token.
@@ -857,6 +861,8 @@ pub enum Nonterminal {
     NtPat(P<ast::Pat>),
     NtExpr(P<ast::Expr>),
     NtTy(P<ast::Ty>),
+    /// The span in the `Ident` is for the identifier passed in to the macro,
+    /// e.g. the `blah` in `foo!(blah)`.
     NtIdent(Ident, IdentIsRaw),
     NtLifetime(Ident),
     NtLiteral(P<ast::Expr>),