rustdoc: Run all work in a separate task

src/librustdoc/lib.rs

@@ -89,7 +89,40 @@ local_data_key!(pub analysiskey: core::CrateAnalysis)
 type Output = (clean::Crate, Vec<plugins::PluginJson> );
 
 pub fn main() {
-    std::os::set_exit_status(main_args(std::os::args().as_slice()));
+    // Why run rustdoc in a separate task? That's a good question!
+    //
+    // We first begin our adventure at the ancient commit of e7c4fb69. In this
+    // commit it was discovered that the stack limit frobbing on windows ended
+    // up causing some syscalls to fail. This was worked around manually in the
+    // relevant location.
+    //
+    // Our journey now continues with #13259 where it was discovered that this
+    // stack limit frobbing has the ability to affect nearly any syscall. Note
+    // that the key idea here is that there is currently no knowledge as to why
+    // this is happening or how to preserve it, fun times!
+    //
+    // Now we continue along to #16275 where it was discovered that --test on
+    // windows didn't work at all! Yet curiously rustdoc worked without --test.
+    // The exact reason that #16275 cropped up is that during the expansion
+    // phase the compiler attempted to open libstd to read out its macros. This
+    // invoked the LLVMRustOpenArchive shim which in turned went to LLVM to go
+    // open a file and read it. Lo and behold this function returned an error!
+    // It was then discovered that when the same fix mentioned in #13259 was
+    // applied, the error went away. The plot thickens!
+    //
+    // Remember that rustdoc works without --test, which raises the question of
+    // how because the --test and non --test paths are almost identical. The
+    // first thing both paths do is parse and expand a crate! It turns out that
+    // the difference is that --test runs on the *main task* while the normal
+    // path runs in subtask. It turns out that running --test in a sub task also
+    // fixes the problem!
+    //
+    // So, in summary, it is unknown why this is necessary, what it is
+    // preventing, or what the actual bug is. In the meantime, this allows
+    // --test to work on windows, which seems good, right? Fun times.
+    spawn(proc() {
+        std::os::set_exit_status(main_args(std::os::args().as_slice()));
+    });
 }
 
 pub fn opts() -> Vec<getopts::OptGroup> {