Update `//@ proc-macro` aux build directive docs (#2149)

Co-authored-by: Eric Huss <eric@huss.org>

2 files changed, 46 insertions, 25 deletions

diff --git a/src/doc/rustc-dev-guide/src/tests/compiletest.md b/src/doc/rustc-dev-guide/src/tests/compiletest.md
index 0ac34793168..ee56b34553a 100644
--- a/src/doc/rustc-dev-guide/src/tests/compiletest.md
+++ b/src/doc/rustc-dev-guide/src/tests/compiletest.md
@@ -572,6 +572,7 @@ There are multiple [directives](directives.md) to assist with that:
 - `aux-crate`
 - `aux-bin`
 - `aux-codegen-backend`
+- `proc-macro`
 
 `aux-build` will build a separate crate from the named source file. The source
 file should be in a directory called `auxiliary` beside the test file.
@@ -604,44 +605,60 @@ for tests in `tests/ui-fulldeps`, since it requires the use of compiler crates.
 
 ### Auxiliary proc-macro
 
-If you want a proc-macro dependency, then there currently is some ceremony
-needed.
+If you want a proc-macro dependency, then you can use the `proc-macro`
+directive. This directive behaves just like `aux-build`, i.e. that you should
+place the proc-macro test auxiliary file under a `auxiliary` folder under the
+same parent folder as the main test file. However, it also has four additional
+preset behavior compared to `aux-build` for the proc-macro test auxiliary:
+
+1. The aux test file is built with `--crate-type=proc-macro`.
+2. The aux test file is built without `-C prefer-dynamic`, i.e. it will not try
+   to produce a dylib for the aux crate.
+3. The aux crate is made available to the test file via extern prelude with
+   `--extern <aux_crate_name>`. Note that since UI tests default to edition
+   2015, you still need to specify `extern <aux_crate_name>` unless the main
+   test file is using an edition that is 2018 or newer if you want to use the
+   aux crate name in a `use` import.
+4. The `proc_macro` crate is made available as an extern prelude module. Same
+   edition 2015 vs newer edition distinction for `extern proc_macro;` applies.
+
+For example, you might have a test `tests/ui/cat/meow.rs` and proc-macro
+auxiliary `tests/ui/cat/auxiliary/whiskers.rs`:
 
-Place the proc-macro itself in a file like `auxiliary/my-proc-macro.rs` with the
-following structure:
+```text
+tests/ui/cat/
+    meow.rs                 # main test file
+    auxiliary/whiskers.rs   # auxiliary
+```
 
-```rust,ignore
-//@ force-host
-//@ no-prefer-dynamic
+```rs
+// tests/ui/cat/meow.rs
 
-#![crate_type = "proc-macro"]
+//@ proc-macro: whiskers.rs
 
-extern crate proc_macro;
-use proc_macro::TokenStream;
+extern crate whiskers; // needed as ui test defaults to edition 2015
 
-#[proc_macro]
-pub fn foo(input: TokenStream) -> TokenStream {
-    "".parse().unwrap()
+fn main() {
+  whiskers::identity!();
 }
 ```
 
-The `force-host` is needed because proc-macros are loaded in the host compiler,
-and `no-prefer-dynamic` is needed to tell compiletest to not use
-`prefer-dynamic` which is not compatible with proc-macros. The `#![crate_type]`
-attribute is needed to specify the correct crate-type.
+```rs
+// tests/ui/cat/auxiliary/whiskers.rs
 
-Then in your test, you can build with `aux-build`:
-
-```rust,ignore
-//@ aux-build: my-proc-macro.rs
-
-extern crate my_proc_macro;
+extern crate proc_macro;
+use proc_macro::*;
 
-fn main() {
-    my_proc_macro::foo!();
+#[proc_macro]
+pub fn identity(ts: TokenStream) -> TokenStream {
+    ts
 }
 ```
 
+> **Note**: The `proc-macro` header currently does not work with the
+> `build-aux-doc` header for rustdoc tests. In that case, you will need to use
+> the `aux-build` header, and use `#![crate_type="proc_macro"]`, and `//@
+> force-host` and `//@ no-prefer-dynamic` headers in the proc-macro.
 
 ## Revisions
 
diff --git a/src/doc/rustc-dev-guide/src/tests/directives.md b/src/doc/rustc-dev-guide/src/tests/directives.md
index b8fba7a6930..132093c36c5 100644
--- a/src/doc/rustc-dev-guide/src/tests/directives.md
+++ b/src/doc/rustc-dev-guide/src/tests/directives.md
@@ -58,8 +58,12 @@ not be exhaustive. Directives can generally be found by browsing the
 | `aux-build`           | Build a separate crate from the named source file                                                     | All except `run-make` | Path to auxiliary `.rs` file                  |
 | `aux-crate`           | Like `aux-build` but makes available as extern prelude                                                | All except `run-make` | `<extern_prelude_name>=<path/to/aux/file.rs>` |
 | `aux-codegen-backend` | Similar to `aux-build` but pass the compiled dylib to `-Zcodegen-backend` when building the main file | `ui-fulldeps`         | Path to codegen backend file                  |
+| `proc-macro`          | Similar to `aux-build`, but for aux forces host and don't use `-Cprefer-dynamic`[^pm].                | All except `run-make` | Path to auxiliary proc-macro `.rs` file       |
 | `build_aux_docs`      | Build docs for auxiliaries as well                                                                    | All except `run-make` | N/A                                           |
 
+[^pm]: please see the Auxiliary proc-macro section in the
+    [compiletest](./compiletest.md) chapter for specifics.
+
 ### Controlling outcome expectations
 
 See [Controlling pass/fail