ci/doc: check for private items as well

We check also the documentation of private items to find linting errors,
such as broken intra-doc links.

Author: phip1611

.github/workflows/rust.yml

@@ -98,7 +98,7 @@ jobs:
           cargo xtask clippy --warnings-as-errors
 
       - name: Run cargo doc
-        run: cargo xtask doc --warnings-as-errors
+        run: cargo xtask doc --warnings-as-errors --document-private-items
 
       - name: Verify generated code is up-to-date
         run: cargo xtask gen-code --check

xtask/src/cargo.rs

@@ -160,7 +160,10 @@ impl TargetTypes {
 pub enum CargoAction {
     Build,
     Clippy,
-    Doc { open: bool },
+    Doc {
+        open: bool,
+        document_private_items: bool,
+    },
     Miri,
     Test,
 }
@@ -235,11 +238,17 @@ impl Cargo {
                     tool_args.extend(["-D", "warnings"]);
                 }
             }
-            CargoAction::Doc { open } => {
+            CargoAction::Doc {
+                open,
+                document_private_items,
+            } => {
                 action = "doc";
                 if self.warnings_as_errors {
                     cmd.env("RUSTDOCFLAGS", "-Dwarnings");
                 }
+                if document_private_items {
+                    extra_args.push("--document-private-items");
+                }
                 if open {
                     extra_args.push("--open");
                 }
@@ -326,7 +335,10 @@ mod tests {
     #[test]
     fn test_cargo_command() {
         let cargo = Cargo {
-            action: CargoAction::Doc { open: true },
+            action: CargoAction::Doc {
+                open: true,
+                document_private_items: true,
+            },
             features: vec![Feature::GlobalAllocator],
             packages: vec![Package::Uefi, Package::Xtask],
             release: false,
@@ -336,7 +348,7 @@ mod tests {
         };
         assert_eq!(
             command_to_string(&cargo.command().unwrap()),
-            "RUSTDOCFLAGS=-Dwarnings cargo doc --package uefi --package xtask --features global_allocator --open"
+            "RUSTDOCFLAGS=-Dwarnings cargo doc --package uefi --package xtask --features global_allocator --document-private-items --open"
         );
     }
 }

xtask/src/main.rs

@@ -86,7 +86,10 @@ fn clippy(opt: &ClippyOpt) -> Result<()> {
 /// Build docs.
 fn doc(opt: &DocOpt) -> Result<()> {
     let cargo = Cargo {
-        action: CargoAction::Doc { open: opt.open },
+        action: CargoAction::Doc {
+            open: opt.open,
+            document_private_items: opt.document_private_items,
+        },
         features: Feature::more_code(),
         packages: Package::published(),
         release: false,

xtask/src/opt.rs

@@ -86,6 +86,11 @@ pub struct DocOpt {
     #[clap(long, action)]
     pub open: bool,
 
+    /// Tells whether private items should be documented. This is convenient to check for
+    /// broken intra-doc links in private items.
+    #[clap(long, action)]
+    pub document_private_items: bool,
+
     #[clap(flatten)]
     pub warning: WarningOpt,
 }