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,
 }