Small changes to ci tool (#13137)

# Objective

- Many of the items in the `ci` tool use `pub(crate)`, which is
functionally equivalent to `pub` when the crate is not a library.
- A few items are missing documentation.

## Solution

- Make all `pub(crate)` items just `pub`.
- `pub` is easier to type and less obscure, and there's not harm from
this change.
- Add / modify documentation on `CI`, `Prepare`, and `PreparedCommand`.

tools/ci/src/ci.rs

@@ -4,9 +4,10 @@ use argh::FromArgs;
 
 /// The CI command line tool for Bevy.
 #[derive(FromArgs)]
-pub(crate) struct CI {
+pub struct CI {
  #[argh(subcommand)]
  command: Option<Commands>,
+
  /// continue running commands even if one fails
  #[argh(switch)]
  keep_going: bool,
@@ -16,7 +17,7 @@ impl CI {
  /// Runs the specified commands or all commands if none are specified.
  ///
  /// When run locally, results may differ from actual CI runs triggered by `.github/workflows/ci.yml`.
- /// This is because the official CI runs latest stable, while local runs use whatever the default Rust is locally.
+ /// This is usually related to differing toolchains and configuration.
  pub fn run(self) {
  let sh = xshell::Shell::new().unwrap();
 
@@ -29,10 +30,13 @@ impl CI {
  // This will automatically move back to the original directory once dropped.
  let _subdir_hook = command.subdir.map(|path| sh.push_dir(path));
 
+ // Execute each command, checking if it returned an error.
  if command.command.envs(command.env_vars).run().is_err() {
  let name = command.name;
  let message = command.failure_message;
+
  if self.keep_going {
+ // We use bullet points here because there can be more than one error.
  failures.push(format!("- {name}: {message}"));
  } else {
  failures.push(format!("{name}: {message}"));
@@ -41,8 +45,10 @@ impl CI {
  }
  }
 
+ // Log errors at the very end.
  if !failures.is_empty() {
  let failures = failures.join("\n");
+
  panic!(
  "One or more CI commands failed:\n\
  {failures}"

tools/ci/src/commands/bench_check.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Checks that the benches compile.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "bench-check")]
-pub(crate) struct BenchCheckCommand {}
+pub struct BenchCheckCommand {}
 
 impl Prepare for BenchCheckCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, _flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/cfg_check.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Checks that the project compiles using the nightly compiler with cfg checks enabled.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "cfg-check")]
-pub(crate) struct CfgCheckCommand {}
+pub struct CfgCheckCommand {}
 
 impl Prepare for CfgCheckCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, _flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/clippy.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Check for clippy warnings and errors.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "clippy")]
-pub(crate) struct ClippyCommand {}
+pub struct ClippyCommand {}
 
 impl Prepare for ClippyCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, _flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/compile.rs

@@ -8,7 +8,7 @@ use argh::FromArgs;
 /// Alias for running the `compile-fail`, `bench-check`, `example-check`, `compile-check`, and `test-check` subcommands.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "compile")]
-pub(crate) struct CompileCommand {}
+pub struct CompileCommand {}
 
 impl Prepare for CompileCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/compile_check.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Checks that the project compiles.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "compile-check")]
-pub(crate) struct CompileCheckCommand {}
+pub struct CompileCheckCommand {}
 
 impl Prepare for CompileCheckCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, _flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/compile_fail.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Runs the compile-fail tests.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "compile-fail")]
-pub(crate) struct CompileFailCommand {}
+pub struct CompileFailCommand {}
 
 impl Prepare for CompileFailCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/doc.rs

@@ -5,7 +5,7 @@ use argh::FromArgs;
 /// Alias for running the `doc-test` and `doc-check` subcommands.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "doc")]
-pub(crate) struct DocCommand {}
+pub struct DocCommand {}
 
 impl Prepare for DocCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/doc_check.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Checks that all docs compile.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "doc-check")]
-pub(crate) struct DocCheckCommand {}
+pub struct DocCheckCommand {}
 
 impl Prepare for DocCheckCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, _flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/doc_test.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Runs all doc tests.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "doc-test")]
-pub(crate) struct DocTestCommand {}
+pub struct DocTestCommand {}
 
 impl Prepare for DocTestCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/example_check.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Checks that the examples compile.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "example-check")]
-pub(crate) struct ExampleCheckCommand {}
+pub struct ExampleCheckCommand {}
 
 impl Prepare for ExampleCheckCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, _flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/format.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Check code formatting.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "format")]
-pub(crate) struct FormatCommand {}
+pub struct FormatCommand {}
 
 impl Prepare for FormatCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, _flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/lints.rs

@@ -5,7 +5,7 @@ use argh::FromArgs;
 /// Alias for running the `format` and `clippy` subcommands.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "lints")]
-pub(crate) struct LintsCommand {}
+pub struct LintsCommand {}
 
 impl Prepare for LintsCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/mod.rs

@@ -1,17 +1,17 @@
-pub(crate) use bench_check::*;
-pub(crate) use cfg_check::*;
-pub(crate) use clippy::*;
-pub(crate) use compile::*;
-pub(crate) use compile_check::*;
-pub(crate) use compile_fail::*;
-pub(crate) use doc::*;
-pub(crate) use doc_check::*;
-pub(crate) use doc_test::*;
-pub(crate) use example_check::*;
-pub(crate) use format::*;
-pub(crate) use lints::*;
-pub(crate) use test::*;
-pub(crate) use test_check::*;
+pub use bench_check::*;
+pub use cfg_check::*;
+pub use clippy::*;
+pub use compile::*;
+pub use compile_check::*;
+pub use compile_fail::*;
+pub use doc::*;
+pub use doc_check::*;
+pub use doc_test::*;
+pub use example_check::*;
+pub use format::*;
+pub use lints::*;
+pub use test::*;
+pub use test_check::*;
 
 mod bench_check;
 mod cfg_check;

tools/ci/src/commands/test.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Runs all tests (except for doc tests).
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "test")]
-pub(crate) struct TestCommand {}
+pub struct TestCommand {}
 
 impl Prepare for TestCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/commands/test_check.rs

@@ -5,7 +5,7 @@ use xshell::cmd;
 /// Checks that all tests compile.
 #[derive(FromArgs, Default)]
 #[argh(subcommand, name = "test-check")]
-pub(crate) struct TestCheckCommand {}
+pub struct TestCheckCommand {}
 
 impl Prepare for TestCheckCommand {
  fn prepare<'a>(&self, sh: &'a xshell::Shell, _flags: Flag) -> Vec<PreparedCommand<'a>> {

tools/ci/src/main.rs

@@ -4,8 +4,8 @@ mod ci;
 mod commands;
 mod prepare;
 
-pub(crate) use self::ci::*;
-pub(crate) use self::prepare::*;
+pub use self::ci::*;
+pub use self::prepare::*;
 
 fn main() {
  argh::from_env::<CI>().run();

tools/ci/src/prepare.rs

@@ -1,20 +1,44 @@
 use bitflags::bitflags;
 
 /// Trait for preparing a subcommand to be run.
-pub(crate) trait Prepare {
+pub trait Prepare {
+ /// A method that returns a list of [`PreparedCommand`]s to be run for a given shell and flags.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use crate::{Flag, Prepare, PreparedCommand};
+ /// # use argh::FromArgs;
+ /// # use xshell::Shell;
+ /// #
+ /// #[derive(FromArgs)]
+ /// #[argh(subcommand, name = "check")]
+ /// struct CheckCommand {}
+ ///
+ /// impl Prepare for CheckCommand {
+ /// fn prepare<'a>(&self, sh: &'a Shell, flags: Flag) -> Vec<PreparedCommand<'a>> {
+ /// vec![PreparedCommand::new::<Self>(
+ /// cmd!(sh, "cargo check --workspace"),
+ /// "Please fix linter errors",
+ /// )]
+ /// }
+ /// }
+ /// ```
  fn prepare<'a>(&self, sh: &'a xshell::Shell, flags: Flag) -> Vec<PreparedCommand<'a>>;
 }
 
 bitflags! {
+ /// Flags that modify how commands are run.
  #[derive(Clone, Copy, Debug, PartialEq, Eq)]
- pub(crate) struct Flag: u32 {
+ pub struct Flag: u32 {
  /// Forces certain checks to continue running even if they hit an error.
  const KEEP_GOING = 1 << 0;
  }
 }
 
+/// A command with associated metadata, created from a command that implements [`Prepare`].
 #[derive(Debug)]
-pub(crate) struct PreparedCommand<'a> {
+pub struct PreparedCommand<'a> {
  /// The name of the command.
  pub name: &'static str,
 
@@ -32,6 +56,13 @@ pub(crate) struct PreparedCommand<'a> {
 }
 
 impl<'a> PreparedCommand<'a> {
+ /// Creates a new [`PreparedCommand`] from a [`Cmd`] and a failure message.
+ ///
+ /// The other fields of [`PreparedCommand`] are filled in with their default values.
+ ///
+ /// For more information about creating a [`Cmd`], please see the [`cmd!`](xshell::cmd) macro.
+ ///
+ /// [`Cmd`]: xshell::Cmd
  pub fn new<T: argh::SubCommand>(
  command: xshell::Cmd<'a>,
  failure_message: &'static str,
@@ -45,11 +76,13 @@ impl<'a> PreparedCommand<'a> {
  }
  }
 
+ /// A builder that overwrites the current sub-directory with a new value.
  pub fn with_subdir(mut self, subdir: &'static str) -> Self {
  self.subdir = Some(subdir);
  self
  }
 
+ /// A builder that adds a new environmental variable to the list.
  pub fn with_env_var(mut self, key: &'static str, value: &'static str) -> Self {
  self.env_vars.push((key, value));
  self