From f8d1dc88a7994d25e481d0272b555b22f9026afb Mon Sep 17 00:00:00 2001
From: Ralf Jung <post@ralfj.de>
Date: Mon, 30 Jul 2018 12:52:01 +0200
Subject: [PATCH 1/2] improve --stage documentation

---
 src/bootstrap/flags.rs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/bootstrap/flags.rs b/src/bootstrap/flags.rs
index 6a013053e580c..23a02c86683b1 100644
--- a/src/bootstrap/flags.rs
+++ b/src/bootstrap/flags.rs
@@ -121,7 +121,10 @@ To learn more about a subcommand, run `./x.py <subcommand> -h`"
         opts.optmulti("", "exclude", "build paths to exclude", "PATH");
         opts.optopt("", "on-fail", "command to run on failure", "CMD");
         opts.optflag("", "dry-run", "dry run; don't build anything");
-        opts.optopt("", "stage", "stage to build", "N");
+        opts.optopt("", "stage",
+            "stage to build (indicates compiler to use/test, e.g. stage 0 uses the \
+             bootstrap compiler, stage 1 the stage 0 rustc artifacts, etc.)",
+            "N");
         opts.optmulti("", "keep-stage", "stage(s) to keep without recompiling", "N");
         opts.optopt("", "src", "path to the root of the rust checkout", "DIR");
         opts.optopt("j", "jobs", "number of jobs to run in parallel", "JOBS");

From aa7d7d0c2b7c85ae860b9eba61d59005b0d049b0 Mon Sep 17 00:00:00 2001
From: Ralf Jung <post@ralfj.de>
Date: Mon, 30 Jul 2018 12:57:20 +0200
Subject: [PATCH 2/2] improve test stage documentation

---
 src/bootstrap/flags.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/bootstrap/flags.rs b/src/bootstrap/flags.rs
index 23a02c86683b1..60b4d65f44401 100644
--- a/src/bootstrap/flags.rs
+++ b/src/bootstrap/flags.rs
@@ -261,7 +261,7 @@ Arguments:
 
         ./x.py build --stage 1 src/libtest
 
-    This will first build everything once (like --stage 0 without further
+    This will first build everything once (like `--stage 0` without further
     arguments would), and then use the compiler built in stage 0 to build
     src/libtest and its dependencies.
     Once this is done, build/$ARCH/stage1 contains a usable compiler.",
@@ -293,10 +293,14 @@ Arguments:
 
         ./x.py test src/test/run-pass
         ./x.py test src/libstd --test-args hash_map
-        ./x.py test src/libstd --stage 0
+        ./x.py test src/libstd --stage 0 --no-doc
         ./x.py test src/test/ui --bless
         ./x.py test src/test/ui --compare-mode nll
 
+    Note that `test src/test/* --stage N` does NOT depend on `build src/rustc --stage N`;
+    just like `build src/libstd --stage N` it tests the compiler produced by the previous
+    stage.
+
     If no arguments are passed then the complete artifacts for that stage are
     compiled and tested.