Deprecate option --test-args in favor of new insta-stable option --test-arg

Author: fmease

src/doc/rustdoc/src/command-line-arguments.md

@@ -194,14 +194,14 @@ $ rustdoc src/lib.rs --test
 This flag will run your code examples as tests. For more, see [the chapter
 on documentation tests](write-documentation/documentation-tests.md).
 
-See also `--test-args` and `--test-run-directory`.
+See also `--test-arg` and `--test-run-directory`.
 
-## `--test-args`: pass options to test runner
+## `--test-arg`: pass an option to the test runner
 
 Using this flag looks like this:
 
 ```bash
-$ rustdoc src/lib.rs --test --test-args ignored
+$ rustdoc src/lib.rs --test --test-arg ignored --test-arg --show-output
 ```
 
 This flag will pass options to the test runner when running documentation tests.
@@ -431,6 +431,10 @@ 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.
 
+## `--test-args`: pass options to the test runner
+
+This flag is **deprecated**, use `--test-arg` instead.
+
 ## `--passes`: add more rustdoc passes
 
 This flag is **deprecated**.

src/librustdoc/config.rs

@@ -618,9 +618,16 @@ impl Options {
             )
             .collect();
 
-        let test_args = matches.opt_strs("test-args");
-        let test_args: Vec<String> =
-            test_args.iter().flat_map(|s| s.split_whitespace()).map(|s| s.to_string()).collect();
+        let mut test_args = matches.opt_strs("test-arg");
+
+        // FIXME: Emit a (hard) deprecation warning in a few releases from the time of writing
+        //        once at least Cargo has had a good chance to migrate to the new flag.
+        test_args.extend(
+            matches.opt_strs("test-args")
+                .iter()
+                .flat_map(|s| s.split_whitespace())
+                .map(|s| s.to_string()),
+        );
 
         let should_test = matches.opt_present("test");
         let no_run = matches.opt_present("no-run");

src/librustdoc/lib.rs

@@ -267,7 +267,14 @@ fn opts() -> Vec<RustcOptGroup> {
             "",
         ),
         opt(Stable, FlagMulti, "", "test", "run code examples as tests", ""),
-        opt(Stable, Multi, "", "test-args", "arguments to pass to the test runner", "ARGS"),
+        opt(
+            Stable,
+            Multi,
+            "",
+            "test-arg",
+            "One argument (of possibly many) to pass to the test runner",
+            "ARG",
+        ),
         opt(
             Stable,
             Opt,
@@ -659,6 +666,14 @@ fn opts() -> Vec<RustcOptGroup> {
             "",
         ),
         // deprecated / removed options
+        opt(
+            Stable,
+            Multi,
+            "",
+            "test-args",
+            "Arguments to pass to the test runner. This option is deprecated, use `--test-arg` instead",
+            "ARGS",
+        ),
         opt(
             Stable,
             Multi,

tests/run-make/doctests-merge/rmake.rs

@@ -9,7 +9,7 @@ fn test_and_compare(input_file: &str, stdout_file: &str, edition: &str, dep: &Pa
         .input(input_file)
         .arg("--test")
         .edition(edition)
-        .arg("--test-args=--test-threads=1")
+        .arg("--test-arg=--test-threads=1")
         .extern_("foo", dep.display().to_string())
         .env("RUST_BACKTRACE", "short")
         .run();

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

@@ -34,8 +34,8 @@ Options:
         --document-hidden-items 
                         document items that have doc(hidden)
         --test          run code examples as tests
-        --test-args ARGS
-                        arguments to pass to the test runner
+        --test-arg ARG  One argument (of possibly many) to pass to the test
+                        runner
         --test-run-directory PATH
                         The working directory in which to run tests
         --target TRIPLE target triple to document
@@ -196,6 +196,9 @@ Options:
         --disable-minification 
                         disable the minification of CSS/JS files
                         (perma-unstable, do not use with cached files)
+        --test-args ARGS
+                        Arguments to pass to the test runner. This option is
+                        deprecated, use `--test-arg` instead
         --plugin-path DIR
                         removed, see issue #44136
                         <https://github.com/rust-lang/rust/issues/44136> for

tests/rustdoc-ui/2024-doctests-checks.rs

@@ -1,6 +1,6 @@
 //@ check-pass
 //@ edition: 2024
-//@ compile-flags: --test --test-args=--test-threads=1
+//@ compile-flags: --test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ normalize-stdout: ".rs:\d+:\d+" -> ".rs:$$LINE:$$COL"

tests/rustdoc-ui/2024-doctests-crate-attribute.rs

@@ -1,6 +1,6 @@
 //@ check-pass
 //@ edition: 2024
-//@ compile-flags: --test --test-args=--test-threads=1
+//@ compile-flags: --test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ normalize-stdout: ".rs:\d+:\d+" -> ".rs:$$LINE:$$COL"

tests/rustdoc-ui/doctest/cfg-test.rs

@@ -1,5 +1,5 @@
 //@ check-pass
-//@ compile-flags:--test --test-args --test-threads=1
+//@ compile-flags:--test --test-arg --test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 

tests/rustdoc-ui/doctest/comment-in-attr-134221-2.rs

@@ -1,4 +1,4 @@
-//@ compile-flags:--test --test-args --test-threads=1
+//@ compile-flags:--test --test-arg --test-threads=1
 //@ failure-status: 101
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"

tests/rustdoc-ui/doctest/comment-in-attr-134221.rs

@@ -2,7 +2,7 @@
 // It checks that even if there are comments in the attributes, the attributes
 // will still be generated correctly (and therefore fail in this test).
 
-//@ compile-flags:--test --test-args --test-threads=1
+//@ compile-flags:--test --test-arg --test-threads=1
 //@ failure-status: 101
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"