---

yaml
---
r: 194332
b: refs/heads/tmp
c: 71b9ba1
h: refs/heads/master
v: v3

Author: steveklabnik

[refs]

@@ -34,7 +34,7 @@ refs/heads/building: 126db549b038c84269a1e4fe46f051b2c15d6970
 refs/heads/beta: a3b13610c5b93d9ada072471a001a5613df6a960
 refs/heads/windistfix: 7608dbad651f02e837ed05eef3d74a6662a6e928
 refs/tags/1.0.0-alpha: e42bd6d93a1d3433c486200587f8f9e12590a4d7
-refs/heads/tmp: 8b6c0fd410ac118e5159b727f33649af5d5442fa
+refs/heads/tmp: 71b9ba1e5b243e52b7c2828e35137eeba378d43f
 refs/tags/1.0.0-alpha.2: 4c705f6bc559886632d3871b04f58aab093bfa2f
 refs/tags/homu-tmp: 28a0b25f424090255966273994748a9f9901059f
 refs/heads/gate: 97c84447b65164731087ea82685580cc81424412

branches/tmp/src/doc/trpl/documentation.md

@@ -333,6 +333,41 @@ By repeating all parts of the example, you can ensure that your example still
 compiles, while only showing the parts that are relevant to that part of your
 explanation.
 
+### Documenting macros
+
+Here’s an example of documenting a macro:
+
+```
+/// Panic with a given message unless an expression evaluates to true.
+///
+/// # Examples
+///
+/// ```
+/// # #[macro_use] extern crate foo;
+/// # fn main() {
+/// panic_unless!(1 + 1 == 2, “Math is broken.”);
+/// # }
+/// ```
+///
+/// ```should_fail
+/// # #[macro_use] extern crate foo;
+/// # fn main() {
+/// panic_unless!(true == false, “I’m broken.”);
+/// # }
+/// ```
+#[macro_export]
+macro_rules! panic_unless {
+    ($condition:expr, $($rest:expr),+) => ({ if ! $condition { panic!($($rest),+); } });
+} 
+```
+
+You’ll note three things: we need to add our own `extern crate` line, so that
+we can add the `#[macro_use]` attribute. Second, we’ll need to add our own
+`main()` as well. Finally, a judicious use of `#` to comment out those two
+things, so they don’t show up in the output.
+
+### Running documentation tests
+
 To run the tests, either
 
 ```bash