Expand reference for macros. (#181)

Fixes: rdar://111068729

Author: amartini51

TSPL.docc/ReferenceManual/Attributes.md

@@ -24,6 +24,12 @@ and how it applies to a particular declaration.
 These *attribute arguments* are enclosed in parentheses,
 and their format is defined by the attribute they belong to.
 
+Attached macros and property wrappers also use attribute syntax.
+For information about how macros expand,
+see <doc:Expressions#Macro-Expansion-Expression>.
+For information about property wrappers,
+see <doc:Attributes#propertyWrapper>.
+
 ## Declaration Attributes
 
 You can apply a declaration attribute to declarations only.

TSPL.docc/ReferenceManual/Declarations.md

@@ -3327,15 +3327,19 @@ macro <#name#> = <#macro implementation#>
 
 The *macro implementation* is another macro,
 and indicates the location of the code that performs this macro's expansion.
+The code that performs macro expansion is a separate Swift program,
+that uses the [SwiftSyntax][] module to interact with Swift code.
 Call the `externalMacro(module:type:)` macro from the Swift standard library,
 passing in the name of a type that contains the macro's implementation,
 and the name of the module that contains that type.
 
+[SwiftSyntax]: http://github.com/apple/swift-syntax/
+
 Macros can be overloaded,
 following the same model used by functions.
 A macro declaration appears only at file scope.
 
-For more information, see <doc:Macros>.
+For an overview of macros in Swift, see <doc:Macros>.
 
 > Grammar of a macro declaration:
 >
@@ -3345,10 +3349,6 @@ For more information, see <doc:Macros>.
 > *macro-function-signature-result* → **`->`** *type* \
 > *macro-definition* → **`=`** *expression*
 
-<!--
-TODO TR: Confirm that the 'where' clause goes after the equals sign.
--->
-
 ## Operator Declaration
 
 An *operator declaration* introduces a new infix, prefix,

TSPL.docc/ReferenceManual/Expressions.md

@@ -1514,18 +1514,60 @@ Macro-expansion expressions have the following form:
 <#macro name#>(<#macro argument 1#>, <#macro argument 2#>)
 ```
 
-A macro-expansion expression omits the parentheses
+A macro-expansion expression omits the parentheses after the macro's name
 if the macro doesn't take any arguments.
 
-A macro expression can't appear as the default value for a parameter,
-except for the [`file()`][] and [`line()`][] macros from the Swift standard library.
+A macro-expansion expression can't appear as the default value for a parameter,
+except the [`file()`][] and [`line()`][] macros from the Swift standard library.
 When used as the default value of a function or method parameter,
-These macros' value is determined
-when the default value expression is evaluated at the call site.
+these macros are evaluated using the source code location of the call site,
+not the location where they appear in a function definition.
 
 [`file()`]: https://developer.apple.com/documentation/swift/file()
 [`line()`]: https://developer.apple.com/documentation/swift/line()
 
+You use macro expressions to call freestanding macros.
+To call an attached macro,
+use the custom attribute syntax described in <doc:Attributes>.
+Both freestanding and attached macros expand as follows:
+
+1. Swift parses the source code
+   to produce an abstract syntax tree (AST).
+
+2. The macro implementation receives AST nodes as its input
+   and performs the transformations needed by that macro.
+
+3. The transformed AST nodes that the macro implementation produced
+   are added to the original AST.
+
+The expansion of each macro is independent and self-contained.
+However, as a performance optimization,
+Swift might start an external process that implements the macro
+and reuse the same process to expand multiple macros.
+When you implement a macro,
+that code must not depend on what macros your code previously expanded,
+or on any other external state like the current time.
+
+For nested macros and attached macros that have multiple roles,
+the expansion process repeats.
+Nested macro-expansion expressions expand from the outside in.
+For example, in the code below
+`outerMacro(_:)` expands first and the unexpanded call to `innerMacro(_:)`
+appears in the abstract syntax tree
+that `outerMacro(_:)` receives as its input.
+
+```swift
+#outerMacro(12, #innerMacro(34), "some text")
+```
+
+An attached macro that has multiple roles expands once for each role.
+Each expansion receives the same, original, AST as its input.
+Swift forms the overall expansion
+by collecting all of the generated AST nodes
+and putting them in their corresponding places in the AST.
+
+For an overview of macros in Swift, see <doc:Macros>.
+
 > Grammar of a macro-expansion expression:
 >
 > *macro-expansion-expression* → **`#`** *identifier* *generic-argument-clause*_?_ *function-call-argument-clause*_?_ *trailing-closures*_?_