Auto merge of #44944 - dbrgn:trace-macros-docs, r=QuietMisdreavus

Docs: Add trace_macros! to unstable book

As TIL'd at Rustfest :)

Note: This is unfortunately untested, since I'm on my laptop battery, and compiling LLVM would probably eat at least 50% of it on my dual core CPU. (Is there a way to build docs without compiling LLVM?)

1 files changed, 39 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/language-features/trace-macros.md b/src/doc/unstable-book/src/language-features/trace-macros.md
new file mode 100644
index 00000000000..41aa286e69b
--- /dev/null
+++ b/src/doc/unstable-book/src/language-features/trace-macros.md
@@ -0,0 +1,39 @@
+# `trace_macros`
+
+The tracking issue for this feature is [#29598].
+
+[#29598]: https://github.com/rust-lang/rust/issues/29598
+
+------------------------
+
+With `trace_macros` you can trace the expansion of macros in your code.
+
+## Examples
+
+```rust
+#![feature(trace_macros)]
+
+fn main() {
+    trace_macros!(true);
+    println!("Hello, Rust!");
+    trace_macros!(false);
+}
+```
+
+The `cargo build` output:
+
+```txt
+note: trace_macro
+ --> src/main.rs:5:5
+  |
+5 |     println!("Hello, Rust!");
+  |     ^^^^^^^^^^^^^^^^^^^^^^^^^
+  |
+  = note: expanding `println! { "Hello, Rust!" }`
+  = note: to `print ! ( concat ! ( "Hello, Rust!" , "\n" ) )`
+  = note: expanding `print! { concat ! ( "Hello, Rust!" , "\n" ) }`
+  = note: to `$crate :: io :: _print ( format_args ! ( concat ! ( "Hello, Rust!" , "\n" ) )
+          )`
+
+    Finished dev [unoptimized + debuginfo] target(s) in 0.60 secs
+```