Document private items for binary crates by default

src/bin/cargo/commands/doc.rs

@@ -55,11 +55,8 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     };
     let mut compile_opts =
         args.compile_options(config, mode, Some(&ws), ProfileChecking::Checked)?;
-    compile_opts.local_rustdoc_args = if args.is_present("document-private-items") {
-        Some(vec!["--document-private-items".to_string()])
-    } else {
-        None
-    };
+    compile_opts.rustdoc_document_private_items = args.is_present("document-private-items");
+
     let doc_opts = DocOptions {
         open_result: args.is_present("open"),
         compile_opts,

src/cargo/ops/cargo_compile.rs

@@ -66,6 +66,9 @@ pub struct CompileOptions<'a> {
     pub target_rustc_args: Option<Vec<String>>,
     /// Extra arguments passed to all selected targets for rustdoc.
     pub local_rustdoc_args: Option<Vec<String>>,
+    /// Whether the `--document-private-items` flags was specified and should
+    /// be forwarded to `rustdoc`.
+    pub rustdoc_document_private_items: bool,
     /// The directory to copy final artifacts to. Note that even if `out_dir` is
     /// set, a copy of artifacts still could be found a `target/(debug\release)`
     /// as usual.
@@ -89,6 +92,7 @@ impl<'a> CompileOptions<'a> {
             target_rustdoc_args: None,
             target_rustc_args: None,
             local_rustdoc_args: None,
+            rustdoc_document_private_items: false,
             export_dir: None,
         })
     }
@@ -271,6 +275,7 @@ pub fn compile_ws<'a>(
         ref target_rustdoc_args,
         ref target_rustc_args,
         ref local_rustdoc_args,
+        rustdoc_document_private_items,
         ref export_dir,
     } = *options;
 
@@ -434,9 +439,20 @@ pub fn compile_ws<'a>(
         }
         bcx.extra_compiler_args.insert(units[0], args);
     }
-    if let Some(args) = local_rustdoc_args {
-        for unit in &units {
-            if unit.mode.is_doc() || unit.mode.is_doc_test() {
+    for unit in &units {
+        if unit.mode.is_doc() || unit.mode.is_doc_test() {
+            let mut extra_args = local_rustdoc_args.clone();
+
+            // Add `--document-private-items` rustdoc flag if requested or if
+            // the target is a binary. Binary crates get their private items
+            // documented by default.
+            if rustdoc_document_private_items || unit.target.is_bin() {
+                let mut args = extra_args.take().unwrap_or(vec![]);
+                args.push("--document-private-items".into());
+                extra_args = Some(args);
+            }
+
+            if let Some(args) = extra_args {
                 bcx.extra_compiler_args.insert(*unit, args.clone());
             }
         }

src/cargo/ops/cargo_package.rs

@@ -661,6 +661,7 @@ fn run_verify(ws: &Workspace<'_>, tar: &FileLock, opts: &PackageOpts<'_>) -> Car
             target_rustdoc_args: None,
             target_rustc_args: rustc_args,
             local_rustdoc_args: None,
+            rustdoc_document_private_items: false,
             export_dir: None,
         },
         &exec,

src/cargo/util/command_prelude.rs

@@ -463,6 +463,7 @@ pub trait ArgMatchesExt {
             target_rustdoc_args: None,
             target_rustc_args: None,
             local_rustdoc_args: None,
+            rustdoc_document_private_items: false,
             export_dir: None,
         };
 

tests/testsuite/doc.rs

@@ -1401,3 +1401,108 @@ fn doc_example() {
         .join("fn.x.html")
         .exists());
 }
+
+#[cargo_test]
+fn bin_private_items() {
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "0.0.1"
+            authors = []
+        "#,
+        )
+        .file(
+            "src/main.rs",
+            "
+            pub fn foo_pub() {}
+            fn foo_priv() {}
+            struct FooStruct;
+            enum FooEnum {}
+            trait FooTrait {}
+            type FooType = u32;
+            mod foo_mod {}
+
+        ",
+        )
+        .build();
+
+    p.cargo("doc")
+        .with_stderr(
+            "\
+[DOCUMENTING] foo v0.0.1 ([CWD])
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]
+",
+        )
+        .run();
+
+    assert!(p.root().join("target/doc/foo/index.html").is_file());
+    assert!(p.root().join("target/doc/foo/fn.foo_pub.html").is_file());
+    assert!(p.root().join("target/doc/foo/fn.foo_priv.html").is_file());
+    assert!(p
+        .root()
+        .join("target/doc/foo/struct.FooStruct.html")
+        .is_file());
+    assert!(p.root().join("target/doc/foo/enum.FooEnum.html").is_file());
+    assert!(p
+        .root()
+        .join("target/doc/foo/trait.FooTrait.html")
+        .is_file());
+    assert!(p.root().join("target/doc/foo/type.FooType.html").is_file());
+    assert!(p.root().join("target/doc/foo/foo_mod/index.html").is_file());
+}
+
+#[cargo_test]
+fn bin_private_items_deps() {
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "0.0.1"
+            authors = []
+
+            [dependencies.bar]
+            path = "bar"
+        "#,
+        )
+        .file(
+            "src/main.rs",
+            "
+            fn foo_priv() {}
+            pub fn foo_pub() {}
+        ",
+        )
+        .file("bar/Cargo.toml", &basic_manifest("bar", "0.0.1"))
+        .file(
+            "bar/src/lib.rs",
+            "
+            #[allow(dead_code)]
+            fn bar_priv() {}
+            pub fn bar_pub() {}
+        ",
+        )
+        .build();
+
+    p.cargo("doc")
+        .with_stderr_unordered(
+            "\
+[DOCUMENTING] bar v0.0.1 ([..])
+[CHECKING] bar v0.0.1 ([..])
+[DOCUMENTING] foo v0.0.1 ([CWD])
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]
+",
+        )
+        .run();
+
+    assert!(p.root().join("target/doc/foo/index.html").is_file());
+    assert!(p.root().join("target/doc/foo/fn.foo_pub.html").is_file());
+    assert!(p.root().join("target/doc/foo/fn.foo_priv.html").is_file());
+
+    assert!(p.root().join("target/doc/bar/index.html").is_file());
+    assert!(p.root().join("target/doc/bar/fn.bar_pub.html").is_file());
+    assert!(!p.root().join("target/doc/bar/fn.bar_priv.html").exists());
+}