From 7e3da5c2ee1ae9237390b4d238d37d8a6c72027a Mon Sep 17 00:00:00 2001
From: Joshua Nelson <jyn514@gmail.com>
Date: Wed, 17 Jun 2020 09:52:39 -0400
Subject: [PATCH] Document rustdoc behavior

- `RUSTDOC_LOG`
- `// aux-build:filename.rs`
- `// build-aux-docs`
---
 src/compiler-debugging.md | 8 ++++++++
 src/rustdoc.md            | 8 ++++++++
 2 files changed, 16 insertions(+)

diff --git a/src/compiler-debugging.md b/src/compiler-debugging.md
index a499224a..0bb3cd1d 100644
--- a/src/compiler-debugging.md
+++ b/src/compiler-debugging.md
@@ -164,6 +164,8 @@ your log filter, e.g. to get the logs for a specific module, you can run the
 compiler as `RUSTC_LOG=module::path rustc my-file.rs`. All `debug!` output will
 then appear in standard error.
 
+If you are developing rustdoc, use `RUSTDOC_LOG` instead.
+
 **Note that unless you use a very strict filter, the logger will emit a lot of
 output, so use the most specific module(s) you can (comma-separated if
 multiple)**. It's typically a good idea to pipe standard error to a file and
@@ -193,6 +195,12 @@ $ RUSTC_LOG=debug rustc +local my-file.rs 2>all-log
 # log rather than a `debug!` log so it will work on the official
 # compilers.
 $ RUSTC_LOG=rustc_trans=info rustc +local my-file.rs
+
+# This will show the output of all `info!` calls made by rustdoc or any rustc library it calls.
+$ RUSTDOC_LOG=info rustdoc +local my-file.rs
+
+# This will only show `debug!` calls made by rustdoc directly, not any `librustc*` crate.
+$ RUSTDOC_LOG=rustdoc rustdoc +local my-file.rs
 ```
 
 ### How to keep or remove `debug!` and `trace!` calls from the resulting binary
diff --git a/src/rustdoc.md b/src/rustdoc.md
index fc964b18..120ebe13 100644
--- a/src/rustdoc.md
+++ b/src/rustdoc.md
@@ -232,6 +232,11 @@ expect in various situations. These tests also use a supplementary script,
 XPath notation to get a precise look at the output. The full description of all
 the commands available to rustdoc tests is in `htmldocck.py`.
 
+To use multiple crates in a rustdoc test, add `// aux-build:filename.rs`
+to the top of the test file. `filename.rs` should be placed in an `auxiliary`
+directory relative to the test file with the comment. If you need to build
+docs for the auxiliary file, use `// build-aux-docs`.
+
 In addition, there are separate tests for the search index and rustdoc's
 ability to query it. The files in `src/test/rustdoc-js` each contain a
 different search query and the expected results, broken out by search tab.
@@ -240,3 +245,6 @@ runtime. These tests don't have as thorough of a writeup, but a broad example
 that features results in all tabs can be found in `basic.js`. The basic idea is
 that you match a given `QUERY` with a set of `EXPECTED` results, complete with
 the full item path of each item.
+
+You can run tests using the name of the folder. For example,
+`x.py test --stage 1 src/test/rustdoc` will run the output tests using a stage1 rustdoc.