Rollup merge of #159415 - notriddle:rename-parts-to-dep-meta, r=GuillaumeGomez

rustdoc: rename the doc parts metadata params

Written in response to #152902 (comment)

Author: JonathanBrouwer

src/doc/rustdoc/src/unstable-features.md

@@ -197,15 +197,26 @@ 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`
+### `--write-doc-meta-dir`, and `--read-doc-meta-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.
+By default, rustdoc will read the doc meta from the doc output dir itself and merge them together.
+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. When
+`--write-doc-meta-dir` and/or `--read-doc-meta-dir` are supplied, this is turned off.
+
+When `--write-doc-meta-dir` is supplied, rustdoc will write the crate's metadata to that directory.
+If this parameter is supplied but `--read-doc-meta-dir` isn't, it runs in *intermediate mode*:
+some pages may be written to the output dir, but there is a lot of functionality that won't work
+until rustdoc is run in *finalize mode*.
+
+When `--read-doc-meta-dir` is supplied, rustdoc runs in *finalize mode*. It will read the data from
+the supplied directory, and will write it to the doc output directory in the form that the web
+frontend will use.
+
+If both `--write-doc-meta-dir` and `--read-doc-meta-dir` are specified, the crate metadata will be
+written to both the HTML `--out-dir` and to the supplied `--write-doc-meta-dir`.
 
 ```console
 $ rustdoc crate1.rs --out-dir=doc
@@ -217,13 +228,13 @@ 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`.
+work, use `--write-doc-meta-dir` on every crate, and the last will use `--read-doc-meta-dir`.
 
 ```console
-$ rustdoc +nightly crate1.rs --merge=none --parts-out-dir=crate1.d -Zunstable-options
+$ rustdoc +nightly crate1.rs --write-doc-meta=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
+$ rustdoc +nightly crate2.rs --read-doc-meta=crate1.d -Zunstable-options
 $ cat doc/search.index/crateNames/*
 rd_("fcrate1fcrate2")
 ```

src/librustdoc/config.rs

@@ -598,34 +598,66 @@ impl Options {
 
         let (lint_opts, describe_lints, lint_cap) = get_cmd_lint_options(early_dcx, matches);
 
-        let input = if describe_lints {
-            InputMode::HasFile(make_input(early_dcx, ""))
-        } else {
-            match matches.free.as_slice() {
-                [] if matches.opt_str("merge").as_deref() == Some("finalize") => {
-                    InputMode::NoInputMergeFinalize
-                }
-                [] => dcx.fatal("missing file operand"),
-                [input] => InputMode::HasFile(make_input(early_dcx, input)),
-                _ => dcx.fatal("too many file operands"),
-            }
-        };
-
         let externs = parse_externs(early_dcx, matches, &unstable_opts);
         let extern_html_root_urls = match parse_extern_html_roots(matches) {
             Ok(ex) => ex,
             Err(err) => dcx.fatal(err),
         };
 
-        let parts_out_dir =
-            match matches.opt_str("parts-out-dir").map(PathToParts::from_flag).transpose() {
+        let mut parts_out_dir =
+            match matches.opt_str("write-doc-meta-dir").map(PathToParts::from_flag).transpose() {
                 Ok(parts_out_dir) => parts_out_dir,
                 Err(e) => dcx.fatal(e),
             };
-        let include_parts_dir = match parse_include_parts_dir(matches) {
+        let mut include_parts_dir = match parse_read_doc_meta(matches, "read-doc-meta-dir") {
             Ok(include_parts_dir) => include_parts_dir,
             Err(e) => dcx.fatal(e),
         };
+        let mut should_merge = compute_should_merge(matches);
+        if parts_out_dir.is_none() && include_parts_dir.is_empty() {
+            // we'll need to get rid of this stuff once Cargo stops using them
+            parts_out_dir =
+                match matches.opt_str("parts-out-dir").map(PathToParts::from_flag).transpose() {
+                    Ok(parts_out_dir) => parts_out_dir,
+                    Err(e) => dcx.fatal(e),
+                };
+            include_parts_dir = match parse_read_doc_meta(matches, "include-parts-dir") {
+                Ok(include_parts_dir) => include_parts_dir,
+                Err(e) => dcx.fatal(e),
+            };
+            should_merge = match matches.opt_str("merge").as_deref() {
+                None => ShouldMerge { read_rendered_cci: true, write_rendered_cci: true },
+                Some("none") => ShouldMerge { read_rendered_cci: false, write_rendered_cci: false },
+                Some("shared") => ShouldMerge { read_rendered_cci: true, write_rendered_cci: true },
+                Some("finalize") => {
+                    ShouldMerge { read_rendered_cci: false, write_rendered_cci: true }
+                }
+                Some(_) => dcx.fatal("argument to --merge must be `none`, `shared`, or `finalize`"),
+            };
+        } else if matches.opt_str("parts-out-dir").is_some() {
+            dcx.fatal(
+                "deprecated version of write-doc-meta-dir is used with new doc-meta-dir stuff",
+            );
+        } else if matches.opt_str("include-parts-dir").is_some() {
+            dcx.fatal(
+                "deprecated version of read-doc-meta-dir is used with new doc-meta-dir stuff",
+            );
+        } else if matches.opt_str("merge").is_some() {
+            dcx.fatal("deprecated parameter merge is used with new doc-meta-dir stuff");
+        }
+
+        let input = if describe_lints {
+            InputMode::HasFile(make_input(early_dcx, ""))
+        } else {
+            match matches.free.as_slice() {
+                [] if !include_parts_dir.is_empty() && should_merge.write_rendered_cci => {
+                    InputMode::NoInputMergeFinalize
+                }
+                [] => dcx.fatal("missing file operand"),
+                [input] => InputMode::HasFile(make_input(early_dcx, input)),
+                _ => dcx.fatal("too many file operands"),
+            }
+        };
 
         let default_settings: Vec<Vec<(String, String)>> = vec![
             matches
@@ -850,10 +882,6 @@ impl Options {
         let extern_html_root_takes_precedence =
             matches.opt_present("extern-html-root-takes-precedence");
         let html_no_source = matches.opt_present("html-no-source");
-        let should_merge = match parse_merge(matches) {
-            Ok(result) => result,
-            Err(e) => dcx.fatal(format!("--merge option error: {e}")),
-        };
         let merge_doctests = parse_merge_doctests(matches, edition, dcx);
         tracing::debug!("merge_doctests: {merge_doctests:?}");
 
@@ -1048,7 +1076,7 @@ impl PathToParts {
         // check here is for diagnostics
         if path.exists() && !path.is_dir() {
             Err(format!(
-                "--parts-out-dir and --include-parts-dir expect directories, found: {}",
+                "--write-doc-meta-dir and --read-doc-meta-dir expect directories, found: {}",
                 path.display(),
             ))
         } else {
@@ -1058,15 +1086,15 @@ impl PathToParts {
     }
 }
 
-/// Reports error if --include-parts-dir is not a directory
-fn parse_include_parts_dir(m: &getopts::Matches) -> Result<Vec<PathToParts>, String> {
+/// Reports error if --read-doc-meta-dir is not a directory
+fn parse_read_doc_meta(m: &getopts::Matches, name: &str) -> Result<Vec<PathToParts>, String> {
     let mut ret = Vec::new();
-    for p in m.opt_strs("include-parts-dir") {
+    for p in m.opt_strs(name) {
         let p = PathToParts::from_flag(p)?;
         // this is just for diagnostic
         if !p.0.is_dir() {
             return Err(format!(
-                "--include-parts-dir expected {} to be a directory",
+                "--read-doc-meta-dir expected {} to be a directory",
                 p.0.display()
             ));
         }
@@ -1086,23 +1114,15 @@ pub(crate) struct ShouldMerge {
 
 /// Extracts read_rendered_cci and write_rendered_cci from command line arguments, or
 /// reports an error if an invalid option was provided
-fn parse_merge(m: &getopts::Matches) -> Result<ShouldMerge, &'static str> {
-    match m.opt_str("merge").as_deref() {
-        // default = read-write
-        None => Ok(ShouldMerge { read_rendered_cci: true, write_rendered_cci: true }),
-        Some("none") if m.opt_present("include-parts-dir") => {
-            Err("--include-parts-dir not allowed if --merge=none")
-        }
-        Some("none") => Ok(ShouldMerge { read_rendered_cci: false, write_rendered_cci: false }),
-        Some("shared") if m.opt_present("parts-out-dir") || m.opt_present("include-parts-dir") => {
-            Err("--parts-out-dir and --include-parts-dir not allowed if --merge=shared")
-        }
-        Some("shared") => Ok(ShouldMerge { read_rendered_cci: true, write_rendered_cci: true }),
-        Some("finalize") if m.opt_present("parts-out-dir") => {
-            Err("--parts-out-dir not allowed if --merge=finalize")
-        }
-        Some("finalize") => Ok(ShouldMerge { read_rendered_cci: false, write_rendered_cci: true }),
-        Some(_) => Err("argument to --merge must be `none`, `shared`, or `finalize`"),
+fn compute_should_merge(m: &getopts::Matches) -> ShouldMerge {
+    match (m.opt_present("read-doc-meta-dir"), m.opt_present("write-doc-meta-dir")) {
+        // shared mode
+        (false, false) => ShouldMerge { read_rendered_cci: true, write_rendered_cci: true },
+        // intermediate mode
+        (false, true) => ShouldMerge { read_rendered_cci: false, write_rendered_cci: false },
+        // finalize mode
+        (true, false) => ShouldMerge { read_rendered_cci: false, write_rendered_cci: true },
+        (true, true) => ShouldMerge { read_rendered_cci: false, write_rendered_cci: true },
     }
 }
 

src/librustdoc/lib.rs

@@ -613,28 +613,41 @@ fn opts() -> Vec<RustcOptGroup> {
             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",
+            "write-doc-meta-dir",
+            "Writes trait implementations and other info for the current crate to provided path",
+            "path/to/doc.meta",
+        ),
+        opt(
+            Unstable,
+            Multi,
+            "",
+            "read-doc-meta-dir",
+            "Includes trait implementations and other crate info from provided path",
+            "path/to/doc.meta",
         ),
         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>",
+            "Deprecated synonym of write-doc-meta-dir",
+            "path/to/doc.meta",
         ),
         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>",
+            "Deprecated synonym of read-doc-meta-dir",
+            "path/to/doc.meta",
+        ),
+        opt(
+            Unstable,
+            Opt,
+            "",
+            "merge",
+            "Deprecated option to specify read/write-doc-meta-dir mode",
+            "none, shared, finalize",
         ),
         opt(Unstable, Flag, "", "html-no-source", "Disable HTML source code pages generation", ""),
         opt(
@@ -758,7 +771,7 @@ fn run_renderer<
 
 /// Renders and writes cross-crate info files, like the search index. This function exists so that
 /// we can run rustdoc without a crate root in the `--merge=finalize` mode. Cross-crate info files
-/// discovered via `--include-parts-dir` are combined and written to the doc root.
+/// discovered via `--read-doc-meta-dir` are combined and written to the doc root.
 fn run_merge_finalize(opt: config::RenderOptions) -> Result<(), error::Error> {
     assert!(
         opt.should_merge.write_rendered_cci,

tests/run-make/rustdoc-default-output/output-default.stdout

@@ -176,23 +176,19 @@ 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>
+        --write-doc-meta-dir path/to/doc.meta
                         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>
+                        current crate to provided path
+        --read-doc-meta-dir path/to/doc.meta
                         Includes trait implementations and other crate info
-                        from provided path. Only use with --merge=finalize
+                        from provided path
+        --parts-out-dir path/to/doc.meta
+                        Deprecated synonym of write-doc-meta-dir
+        --include-parts-dir path/to/doc.meta
+                        Deprecated synonym of read-doc-meta-dir
+        --merge none, shared, finalize
+                        Deprecated option to specify read/write-doc-meta-dir
+                        mode
         --html-no-source 
                         Disable HTML source code pages generation
         --doctest-build-arg ARG

tests/run-make/rustdoc-merge-directory-alias/rmake.rs

@@ -1,4 +1,4 @@
-// Running --merge=finalize without an input crate root should not trigger ICE.
+// Running --read-doc-meta-dir without an input crate root should not trigger ICE.
 // Issue: https://github.com/rust-lang/rust/issues/146646
 
 //@ needs-target-std
@@ -14,71 +14,63 @@ fn main() {
         .input("dep1.rs")
         .out_dir(&out_dir)
         .arg("-Zunstable-options")
-        .arg(format!("--parts-out-dir={}", parts_out_dir.display()))
-        .arg("--merge=none")
+        .arg(format!("--write-doc-meta-dir={}", parts_out_dir.display()))
         .run();
     assert!(parts_out_dir.join("dep1.json").exists());
 
     let output = rustdoc()
         .arg("-Zunstable-options")
         .out_dir(&out_dir)
-        .arg(format!("--include-parts-dir={}", parts_out_dir.display()))
-        .arg("--merge=finalize")
+        .arg(format!("--read-doc-meta-dir={}", parts_out_dir.display()))
         .run();
     output.assert_stderr_not_contains("error: the compiler unexpectedly panicked. this is a bug.");
 
     rustdoc()
         .input("dep2.rs")
         .out_dir(&out_dir)
         .arg("-Zunstable-options")
-        .arg(format!("--parts-out-dir={}", parts_out_dir.display()))
-        .arg("--merge=none")
+        .arg(format!("--write-doc-meta-dir={}", parts_out_dir.display()))
         .run();
     assert!(parts_out_dir.join("dep2.json").exists());
 
     let output2 = rustdoc()
         .arg("-Zunstable-options")
         .out_dir(&out_dir)
-        .arg(format!("--include-parts-dir={}", parts_out_dir.display()))
-        .arg("--merge=finalize")
+        .arg(format!("--read-doc-meta-dir={}", parts_out_dir.display()))
         .run();
     output2.assert_stderr_not_contains("error: the compiler unexpectedly panicked. this is a bug.");
 
     rustdoc()
         .input("dep1.rs")
         .out_dir(&out_dir)
         .arg("-Zunstable-options")
-        .arg(format!("--parts-out-dir={}", parts_out_dir.display()))
-        .arg("--merge=none")
+        .arg(format!("--write-doc-meta-dir={}", parts_out_dir.display()))
         .run();
     assert!(parts_out_dir.join("dep1.json").exists());
 
     let output3 = rustdoc()
         .arg("-Zunstable-options")
         .out_dir(&out_dir)
-        .arg(format!("--include-parts-dir={}", parts_out_dir.display()))
-        .arg("--merge=finalize")
+        .arg(format!("--read-doc-meta-dir={}", parts_out_dir.display()))
         .run();
     output3.assert_stderr_not_contains("error: the compiler unexpectedly panicked. this is a bug.");
 
-    // dep_missing is different, because --parts-out-dir is not supplied
+    // dep_missing is different, because --write-doc-meta-dir is not supplied
     rustdoc().input("dep_missing.rs").out_dir(&out_dir).run();
     assert!(parts_out_dir.join("dep2.json").exists());
 
     rustdoc()
         .input("dep1.rs")
         .out_dir(&out_dir)
         .arg("-Zunstable-options")
-        .arg(format!("--parts-out-dir={}", parts_out_dir.display()))
-        .arg("--merge=none")
+        .arg(format!("--write-doc-meta-dir={}", parts_out_dir.display()))
         .run();
     assert!(parts_out_dir.join("dep1.json").exists());
 
     let output4 = rustdoc()
         .arg("-Zunstable-options")
         .out_dir(&out_dir)
-        .arg(format!("--include-parts-dir={}", parts_out_dir.display()))
-        .arg("--merge=finalize")
+        .arg(format!("--read-doc-meta-dir={}", parts_out_dir.display()))
         .run();
     output4.assert_stderr_not_contains("error: the compiler unexpectedly panicked. this is a bug.");