Document rustdoc behavior

- `RUSTDOC_LOG`
- `// aux-build:filename.rs`
- `// build-aux-docs`

Author: jyn514

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

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.