Rollup merge of #91310 - hi-rustin:rustin-patch-rustdoc, r=jyn514

Add --out-dir flag for rustdoc

part of #91260

Add --out-dir flag for rustdoc and change the `-o` option to point to out-dir.

I'm not quite sure if it should be stable, also I'm not sure if this parameter priority is appropriate? Or should I just refuse to pass both parameters at the same time?

r? `@jyn514`

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

@@ -57,13 +57,13 @@ release: 1.17.0
 LLVM version: 3.9
 ```
 
-## `-o`/`--output`: output path
+## `-o`/`--out-dir`: output directory path
 
 Using this flag looks like this:
 
 ```bash
 $ rustdoc src/lib.rs -o target/doc
-$ rustdoc src/lib.rs --output target/doc
+$ rustdoc src/lib.rs --out-dir target/doc
 ```
 
 By default, `rustdoc`'s output appears in a directory named `doc` in

src/librustdoc/config.rs

@@ -504,8 +504,18 @@ impl Options {
             return Err(1);
         }
 
-        let output =
-            matches.opt_str("o").map(|s| PathBuf::from(&s)).unwrap_or_else(|| PathBuf::from("doc"));
+        let out_dir = matches.opt_str("out-dir").map(|s| PathBuf::from(&s));
+        let output = matches.opt_str("output").map(|s| PathBuf::from(&s));
+        let output = match (out_dir, output) {
+            (Some(_), Some(_)) => {
+                diag.struct_err("cannot use both 'out-dir' and 'output' at once").emit();
+                return Err(1);
+            }
+            (Some(out_dir), None) => out_dir,
+            (None, Some(output)) => output,
+            (None, None) => PathBuf::from("doc"),
+        };
+
         let cfgs = matches.opt_strs("cfg");
 
         let extension_css = matches.opt_str("e").map(|s| PathBuf::from(&s));

src/librustdoc/lib.rs

@@ -278,7 +278,16 @@ fn opts() -> Vec<RustcOptGroup> {
             o.optopt("r", "input-format", "the input type of the specified file", "[rust]")
         }),
         stable("w", |o| o.optopt("w", "output-format", "the output type to write", "[html]")),
-        stable("o", |o| o.optopt("o", "output", "where to place the output", "PATH")),
+        stable("output", |o| {
+            o.optopt(
+                "",
+                "output",
+                "Which directory to place the output. \
+                 This option is deprecated, use --out-dir instead.",
+                "PATH",
+            )
+        }),
+        stable("o", |o| o.optopt("o", "out-dir", "which directory to place the output", "PATH")),
         stable("crate-name", |o| {
             o.optopt("", "crate-name", "specify the name of this crate", "NAME")
         }),

src/test/run-make/rustdoc-with-out-dir-option/Makefile

@@ -0,0 +1,8 @@
+-include ../../run-make-fulldeps/tools.mk
+
+OUTPUT_DIR := "$(TMPDIR)/rustdoc"
+
+all:
+	$(RUSTDOC) src/lib.rs --crate-name foobar --crate-type lib --out-dir $(OUTPUT_DIR)
+
+	$(HTMLDOCCK) $(OUTPUT_DIR) src/lib.rs

src/test/run-make/rustdoc-with-out-dir-option/src/lib.rs

@@ -0,0 +1,2 @@
+// @has foobar/fn.ok.html
+pub fn ok() {}

src/test/run-make/rustdoc-with-output-option/Makefile

@@ -0,0 +1,8 @@
+-include ../../run-make-fulldeps/tools.mk
+
+OUTPUT_DIR := "$(TMPDIR)/rustdoc"
+
+all:
+	$(RUSTDOC) src/lib.rs --crate-name foobar --crate-type lib --output $(OUTPUT_DIR)
+
+	$(HTMLDOCCK) $(OUTPUT_DIR) src/lib.rs

src/test/run-make/rustdoc-with-output-option/src/lib.rs

@@ -0,0 +1,2 @@
+// @has foobar/fn.ok.html
+pub fn ok() {}

src/test/run-make/rustdoc-with-short-out-dir-option/Makefile

@@ -0,0 +1,8 @@
+-include ../../run-make-fulldeps/tools.mk
+
+OUTPUT_DIR := "$(TMPDIR)/rustdoc"
+
+all:
+	$(RUSTDOC) src/lib.rs --crate-name foobar --crate-type lib -o $(OUTPUT_DIR)
+
+	$(HTMLDOCCK) $(OUTPUT_DIR) src/lib.rs

src/test/run-make/rustdoc-with-short-out-dir-option/src/lib.rs

@@ -0,0 +1,2 @@
+// @has foobar/fn.ok.html
+pub fn ok() {}

src/test/rustdoc-ui/use_both_out_dir_and_output_options.rs

@@ -0,0 +1 @@
+// compile-flags: --output ./foo

src/test/rustdoc-ui/use_both_out_dir_and_output_options.stderr

@@ -0,0 +1,2 @@
+error: cannot use both 'out-dir' and 'output' at once
+