bootstrap: Promote some build_steps comments to docs

src/bootstrap/src/core/build_steps/check.rs

@@ -394,7 +394,7 @@ pub struct $name {
         impl Step for $name {
             type Output = ();
             const ONLY_HOSTS: bool = true;
-            // don't ever check out-of-tree tools by default, they'll fail when toolstate is broken
+            /// don't ever check out-of-tree tools by default, they'll fail when toolstate is broken
             const DEFAULT: bool = matches!($source_type, SourceType::InTree) $( && $default )?;
 
             fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {

src/bootstrap/src/core/build_steps/clippy.rs

@@ -24,7 +24,7 @@
 use super::tool::prepare_tool_cargo;
 use super::tool::SourceType;
 
-// Disable the most spammy clippy lints
+/// Disable the most spammy clippy lints
 const IGNORED_RULES_FOR_STD_AND_RUSTC: &[&str] = &[
     "many_single_char_names", // there are a lot in stdarch
     "collapsible_if",

src/bootstrap/src/core/build_steps/compile.rs

@@ -835,13 +835,13 @@ pub fn new(compiler: Compiler, target: TargetSelection) -> Self {
 }
 
 impl Step for Rustc {
-    // We return the stage of the "actual" compiler (not the uplifted one).
-    //
-    // By "actual" we refer to the uplifting logic where we may not compile the requested stage;
-    // instead, we uplift it from the previous stages. Which can lead to bootstrap failures in
-    // specific situations where we request stage X from other steps. However we may end up
-    // uplifting it from stage Y, causing the other stage to fail when attempting to link with
-    // stage X which was never actually built.
+    /// We return the stage of the "actual" compiler (not the uplifted one).
+    ///
+    /// By "actual" we refer to the uplifting logic where we may not compile the requested stage;
+    /// instead, we uplift it from the previous stages. Which can lead to bootstrap failures in
+    /// specific situations where we request stage X from other steps. However we may end up
+    /// uplifting it from stage Y, causing the other stage to fail when attempting to link with
+    /// stage X which was never actually built.
     type Output = u32;
     const ONLY_HOSTS: bool = true;
     const DEFAULT: bool = false;
@@ -1302,7 +1302,7 @@ fn is_codegen_cfg_needed(path: &TaskPath, run: &RunConfig<'_>) -> bool {
 impl Step for CodegenBackend {
     type Output = ();
     const ONLY_HOSTS: bool = true;
-    // Only the backends specified in the `codegen-backends` entry of `config.toml` are built.
+    /// Only the backends specified in the `codegen-backends` entry of `config.toml` are built.
     const DEFAULT: bool = true;
 
     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {

src/bootstrap/src/core/build_steps/dist.rs

@@ -2272,9 +2272,9 @@ fn run(self, builder: &Builder<'_>) -> Option<GeneratedTarball> {
     }
 }
 
-// Tarball intended for internal consumption to ease rustc/std development.
-//
-// Should not be considered stable by end users.
+/// Tarball intended for internal consumption to ease rustc/std development.
+///
+/// Should not be considered stable by end users.
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 pub struct RustDev {
     pub target: TargetSelection,
@@ -2356,9 +2356,9 @@ fn run(self, builder: &Builder<'_>) -> Option<GeneratedTarball> {
     }
 }
 
-// Tarball intended for internal consumption to ease rustc/std development.
-//
-// Should not be considered stable by end users.
+/// Tarball intended for internal consumption to ease rustc/std development.
+///
+/// Should not be considered stable by end users.
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 pub struct Bootstrap {
     pub target: TargetSelection,

src/bootstrap/src/core/build_steps/doc.rs

@@ -506,7 +506,7 @@ fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
         run.never()
     }
 
-    // Generate shared resources used by other pieces of documentation.
+    /// Generate shared resources used by other pieces of documentation.
     fn run(self, builder: &Builder<'_>) -> Self::Output {
         let out = builder.doc_out(self.target);
 

src/bootstrap/src/core/build_steps/install.rs

@@ -20,8 +20,8 @@
 #[cfg(not(target_os = "illumos"))]
 const SHELL: &str = "sh";
 
-// We have to run a few shell scripts, which choke quite a bit on both `\`
-// characters and on `C:\` paths, so normalize both of them away.
+/// We have to run a few shell scripts, which choke quite a bit on both `\`
+/// characters and on `C:\` paths, so normalize both of them away.
 fn sanitize_sh(path: &Path) -> String {
     let path = path.to_str().unwrap().replace('\\', "/");
     return change_drive(unc_to_lfs(&path)).unwrap_or(path);

src/bootstrap/src/core/build_steps/llvm.rs

@@ -56,14 +56,14 @@ pub fn should_build(&self) -> bool {
     }
 }
 
-// Linker flags to pass to LLVM's CMake invocation.
+/// Linker flags to pass to LLVM's CMake invocation.
 #[derive(Debug, Clone, Default)]
 struct LdFlags {
-    // CMAKE_EXE_LINKER_FLAGS
+    /// CMAKE_EXE_LINKER_FLAGS
     exe: OsString,
-    // CMAKE_SHARED_LINKER_FLAGS
+    /// CMAKE_SHARED_LINKER_FLAGS
     shared: OsString,
-    // CMAKE_MODULE_LINKER_FLAGS
+    /// CMAKE_MODULE_LINKER_FLAGS
     module: OsString,
 }
 

src/bootstrap/src/core/build_steps/test.rs

@@ -1433,8 +1433,8 @@ fn run(self, builder: &Builder<'_>) -> PathBuf {
 
 host_test!(Pretty { path: "tests/pretty", mode: "pretty", suite: "pretty" });
 
-// Special-handling is needed for `run-make`, so don't use `default_test` for defining `RunMake`
-// tests.
+/// Special-handling is needed for `run-make`, so don't use `default_test` for defining `RunMake`
+/// tests.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub struct RunMake {
     pub compiler: Compiler,
@@ -1527,10 +1527,10 @@ fn run_coverage_tests(
 
 impl Step for Coverage {
     type Output = ();
-    // We rely on the individual CoverageMap/CoverageRun steps to run themselves.
+    /// We rely on the individual CoverageMap/CoverageRun steps to run themselves.
     const DEFAULT: bool = false;
-    // When manually invoked, try to run as much as possible.
-    // Compiletest will automatically skip the "coverage-run" tests if necessary.
+    /// When manually invoked, try to run as much as possible.
+    /// Compiletest will automatically skip the "coverage-run" tests if necessary.
     const ONLY_HOSTS: bool = false;
 
     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {