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,20 @@ 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");
+
+ let deprecated_test_args = matches.opt_strs("test-args");
+ if !deprecated_test_args.is_empty() {
+ dcx.struct_warn("`--test-args ARGS`: this option is deprecated")
+ .with_help("use `--test-arg ARG` per ARG in ARGS instead")
+ .emit();
+ test_args.extend(
+ deprecated_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"