Stabilize rustdoc --merge --parts-out-dir, and --include-parts-dir options

GuillaumeGomez · GuillaumeGomez · commit 8f3b559ec472 · 2026-02-23T16:55:07.000+01:00
diff --git a/src/doc/rustdoc/src/command-line-arguments.md b/src/doc/rustdoc/src/command-line-arguments.md
@@ -453,6 +453,35 @@ command line options from it. These options are one per line; a blank line indic
 an empty option. The file can use Unix or Windows style line endings, and must be
 encoded as UTF-8.
 
+## `--merge`, `--parts-out-dir` and `--include-parts-dir`: control how rustdoc handles files that combine data from multiple crates
+
+By default, they act like `--merge=shared` is set, and `--parts-out-dir` and `--include-parts-dir`
+are turned off. The `--merge=shared` mode causes rustdoc to load the existing data in the out-dir,
+combine the new crate data into it, and write the result. This is very easy to use in scripts that
+manually invoke rustdoc, but it's also slow, because it performs O(crates) work on
+every crate, meaning it performs O(crates<sup>2</sup>) work.
+
+```console
+$ rustdoc crate1.rs --out-dir=doc
+$ cat doc/search.index/crateNames/*
+rd_("fcrate1")
+$ rustdoc crate2.rs --out-dir=doc
+$ cat doc/search.index/crateNames/*
+rd_("fcrate1fcrate2")
+```
+
+To delay shared-data merging until the end of a build, so that you only have to perform O(crates)
+work, use `--merge=none` on every crate except the last one, which will use `--merge=finalize`.
+
+```console
+$ rustdoc +nightly crate1.rs --merge=none --parts-out-dir=crate1.d -Zunstable-options
+$ cat doc/search.index/crateNames/*
+cat: 'doc/search.index/crateNames/*': No such file or directory
+$ rustdoc +nightly crate2.rs --merge=finalize --include-parts-dir=crate1.d -Zunstable-options
+$ cat doc/search.index/crateNames/*
+rd_("fcrate1fcrate2")
+```
+
 ## `--passes`: add more rustdoc passes
 
 This flag is **deprecated**.
diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md
@@ -197,37 +197,6 @@ themselves marked as unstable. To use any of these options, pass `-Z unstable-op
 the flag in question to Rustdoc on the command-line. To do this from Cargo, you can either use the
 `RUSTDOCFLAGS` environment variable or the `cargo rustdoc` command.
 
-### `--merge`, `--parts-out-dir`, and `--include-parts-dir`
-
-These options control how rustdoc handles files that combine data from multiple crates.
-
-By default, they act like `--merge=shared` is set, and `--parts-out-dir` and `--include-parts-dir`
-are turned off. The `--merge=shared` mode causes rustdoc to load the existing data in the out-dir,
-combine the new crate data into it, and write the result. This is very easy to use in scripts that
-manually invoke rustdoc, but it's also slow, because it performs O(crates) work on
-every crate, meaning it performs O(crates<sup>2</sup>) work.
-
-```console
-$ rustdoc crate1.rs --out-dir=doc
-$ cat doc/search.index/crateNames/*
-rd_("fcrate1")
-$ rustdoc crate2.rs --out-dir=doc
-$ cat doc/search.index/crateNames/*
-rd_("fcrate1fcrate2")
-```
-
-To delay shared-data merging until the end of a build, so that you only have to perform O(crates)
-work, use `--merge=none` on every crate except the last one, which will use `--merge=finalize`.
-
-```console
-$ rustdoc +nightly crate1.rs --merge=none --parts-out-dir=crate1.d -Zunstable-options
-$ cat doc/search.index/crateNames/*
-cat: 'doc/search.index/crateNames/*': No such file or directory
-$ rustdoc +nightly crate2.rs --merge=finalize --include-parts-dir=crate1.d -Zunstable-options
-$ cat doc/search.index/crateNames/*
-rd_("fcrate1fcrate2")
-```
-
 ### `--document-hidden-items`: Show items that are `#[doc(hidden)]`
 <span id="document-hidden-items"></span>
 
diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs
@@ -599,33 +599,6 @@ fn opts() -> Vec<RustcOptGroup> {
             "",
             "path to function call information (for displaying examples in the documentation)",
         ),
-        opt(
-            Unstable,
-            Opt,
-            "",
-            "merge",
-            "Controls how rustdoc handles files from previously documented crates in the doc root\n\
-                none = Do not write cross-crate information to the --out-dir\n\
-                shared = Append current crate's info to files found in the --out-dir\n\
-                finalize = Write current crate's info and --include-parts-dir info to the --out-dir, overwriting conflicting files",
-            "none|shared|finalize",
-        ),
-        opt(
-            Unstable,
-            Opt,
-            "",
-            "parts-out-dir",
-            "Writes trait implementations and other info for the current crate to provided path. Only use with --merge=none",
-            "path/to/doc.parts/<crate-name>",
-        ),
-        opt(
-            Unstable,
-            Multi,
-            "",
-            "include-parts-dir",
-            "Includes trait implementations and other crate info from provided path. Only use with --merge=finalize",
-            "path/to/doc.parts/<crate-name>",
-        ),
         opt(Unstable, Flag, "", "html-no-source", "Disable HTML source code pages generation", ""),
         opt(
             Unstable,
@@ -692,6 +665,33 @@ fn opts() -> Vec<RustcOptGroup> {
             "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information",
             "[rust]",
         ),
+        opt(
+            Stable,
+            Opt,
+            "",
+            "merge",
+            "Controls how rustdoc handles files from previously documented crates in the doc root\n\
+                none = Do not write cross-crate information to the --out-dir\n\
+                shared = Append current crate's info to files found in the --out-dir\n\
+                finalize = Write current crate's info and --include-parts-dir info to the --out-dir, overwriting conflicting files",
+            "none|shared|finalize",
+        ),
+        opt(
+            Stable,
+            Opt,
+            "",
+            "parts-out-dir",
+            "Writes trait implementations and other info for the current crate to provided path. Only use with --merge=none",
+            "path/to/doc.parts/<crate-name>",
+        ),
+        opt(
+            Stable,
+            Multi,
+            "",
+            "include-parts-dir",
+            "Includes trait implementations and other crate info from provided path. Only use with --merge=finalize",
+            "path/to/doc.parts/<crate-name>",
+        ),
     ]
 }
 
diff --git a/tests/run-make/rustdoc-default-output/output-default.stdout b/tests/run-make/rustdoc-default-output/output-default.stdout
@@ -173,23 +173,6 @@ Options:
         --scrape-tests  Include test code when scraping examples
         --with-examples path to function call information (for displaying examples in the documentation)
                         
-        --merge none|shared|finalize
-                        Controls how rustdoc handles files from previously
-                        documented crates in the doc root
-                        none = Do not write cross-crate information to the
-                        --out-dir
-                        shared = Append current crate's info to files found in
-                        the --out-dir
-                        finalize = Write current crate's info and
-                        --include-parts-dir info to the --out-dir, overwriting
-                        conflicting files
-        --parts-out-dir path/to/doc.parts/<crate-name>
-                        Writes trait implementations and other info for the
-                        current crate to provided path. Only use with
-                        --merge=none
-        --include-parts-dir path/to/doc.parts/<crate-name>
-                        Includes trait implementations and other crate info
-                        from provided path. Only use with --merge=finalize
         --html-no-source 
                         Disable HTML source code pages generation
         --doctest-build-arg ARG
@@ -219,6 +202,23 @@ Options:
                         removed, see issue #44136
                         <https://github.com/rust-lang/rust/issues/44136> for
                         more information
+        --merge none|shared|finalize
+                        Controls how rustdoc handles files from previously
+                        documented crates in the doc root
+                        none = Do not write cross-crate information to the
+                        --out-dir
+                        shared = Append current crate's info to files found in
+                        the --out-dir
+                        finalize = Write current crate's info and
+                        --include-parts-dir info to the --out-dir, overwriting
+                        conflicting files
+        --parts-out-dir path/to/doc.parts/<crate-name>
+                        Writes trait implementations and other info for the
+                        current crate to provided path. Only use with
+                        --merge=none
+        --include-parts-dir path/to/doc.parts/<crate-name>
+                        Includes trait implementations and other crate info
+                        from provided path. Only use with --merge=finalize
 
     @path               Read newline separated options from `path`
 
