Document all public items of the CLI (#388)

It got discussed in the [CLI working-group
](https://discord.com/channels/691052431525675048/1278871953721262090/1364297693182300312)
that the Bevy editor also uses the CLI as a library. To make it easier
for them, we should "stabilize" our public interface for `0.1.0` and add
some short comments on the public types.

---------

Co-authored-by: TimJentzsch <[email protected]>

Author: DaAlbrecht

src/bin/main.rs

@@ -54,6 +54,9 @@ pub struct Cli {
     /// Available subcommands for the Bevy CLI.
     #[command(subcommand)]
     pub subcommand: Subcommands,
+    /// Use verbose output.
+    ///
+    /// Logs commands that are executed and more information on the actions being performed.
     #[arg(long, short = 'v', global = true)]
     pub verbose: bool,
 }

src/build/args.rs

@@ -8,6 +8,7 @@ use crate::{
     },
 };
 
+/// Arguments for building a Bevy project.
 #[derive(Debug, Args)]
 pub struct BuildArgs {
     /// The subcommands available for the build command.
@@ -94,13 +95,15 @@ impl BuildArgs {
     }
 }
 
+/// The subcommands available for the build command.
 #[derive(Debug, Subcommand)]
 pub enum BuildSubcommands {
     /// Build your app for the browser.
     #[cfg(feature = "web")]
     Web(BuildWebArgs),
 }
 
+/// Additional Arguments for building a Bevy web project.
 #[derive(Debug, Args)]
 pub struct BuildWebArgs {
     // Bundle all web artifacts into a single folder.

src/build/mod.rs

@@ -1,3 +1,5 @@
+//! Provides functionalities to build a Bevy app targeting either native or web platforms.
+
 use args::BuildArgs;
 
 #[cfg(feature = "web")]
@@ -6,6 +8,11 @@ use crate::{bin_target::select_run_binary, config::CliConfig, external_cli::carg
 
 pub mod args;
 
+/// Tries to build the project with the given [`BuildArgs`].
+///
+/// # Errors
+///
+/// will error if the build process can not be completed
 pub fn build(args: &mut BuildArgs) -> anyhow::Result<()> {
     let metadata = cargo::metadata::metadata()?;
 

src/config.rs

@@ -1,3 +1,4 @@
+//! Configuration used by the `bevy_cli`, defined in `Cargo.toml` under `package.metadata.bevy_cli`.
 use std::fmt::Display;
 
 use anyhow::{Context, bail};
@@ -6,6 +7,13 @@ use serde_json::{Map, Value};
 
 use crate::external_cli::cargo::metadata::{Metadata, Package};
 
+/// Configuration for the `bevy_cli`.
+///
+/// Allows customizing:
+/// - Target platform
+/// - Enabled features
+/// - Whether to enable default features
+/// - Additional Rust compiler flags
 #[derive(Default, Debug, Clone, PartialEq, Serialize)]
 pub struct CliConfig {
     /// The platform to target with the build.

src/external_cli/arg_builder.rs

@@ -13,7 +13,7 @@ impl ArgBuilder {
     ///
     /// # Example
     ///
-    /// ```
+    /// ```ignore
     /// # use bevy_cli::external_cli::arg_builder::ArgBuilder;
     /// ArgBuilder::new().arg("--release");
     /// ```
@@ -29,7 +29,7 @@ impl ArgBuilder {
     ///
     /// # Example
     ///
-    /// ```
+    /// ```ignore
     /// # use bevy_cli::external_cli::arg_builder::ArgBuilder;
     /// ArgBuilder::new().add_with_value("--bin", "bevy");
     /// ```
@@ -45,7 +45,7 @@ impl ArgBuilder {
     ///
     /// # Example
     ///
-    /// ```
+    /// ```ignore
     /// # use bevy_cli::external_cli::arg_builder::ArgBuilder;
     /// let is_release = true;
     /// ArgBuilder::new().add_flag_if("--release", is_release);
@@ -63,7 +63,7 @@ impl ArgBuilder {
     ///
     /// # Example
     ///
-    /// ```
+    /// ```ignore
     /// # use bevy_cli::external_cli::arg_builder::ArgBuilder;
     /// let maybe_name = Some("bevy");
     /// ArgBuilder::new().add_opt_value("--bin", &maybe_name);
@@ -84,7 +84,7 @@ impl ArgBuilder {
     ///
     /// # Example
     ///
-    /// ```
+    /// ```ignore
     /// # use bevy_cli::external_cli::arg_builder::ArgBuilder;
     /// let features = ["dev", "file_watcher"];
     /// ArgBuilder::new().add_value_list("--features", features);
@@ -108,7 +108,7 @@ impl ArgBuilder {
     ///
     /// # Example
     ///
-    /// ```
+    /// ```ignore
     /// # use bevy_cli::external_cli::arg_builder::ArgBuilder;
     /// let features = ["dev", "file_watcher"];
     /// ArgBuilder::new().add_values_separately("--features", features);

src/external_cli/mod.rs

@@ -10,7 +10,7 @@ use cargo::install::AutoInstall;
 use semver::VersionReq;
 use tracing::{Level, debug, error, info, trace, warn};
 
-pub mod arg_builder;
+pub(crate) mod arg_builder;
 pub(crate) mod cargo;
 #[cfg(feature = "rustup")]
 pub(crate) mod rustup;
@@ -53,6 +53,7 @@ impl CommandExt {
     ///
     /// If the command fails and the package is missing,
     /// it can be installed automatically via `cargo install`.
+    #[cfg(feature = "web")]
     pub fn require_package<S: AsRef<OsStr>>(&mut self, name: S, version: VersionReq) -> &mut Self {
         self.package = Some(Package {
             name: name.as_ref().to_owned(),
@@ -65,6 +66,7 @@ impl CommandExt {
     ///
     /// If the command fails and the target is missing,
     /// it can be installed automatically via `rustup`.
+    #[cfg(feature = "web")]
     pub fn maybe_require_target<S: AsRef<OsStr>>(&mut self, target: Option<S>) -> &mut Self {
         if let Some(target) = target {
             self.target = Some(target.as_ref().to_owned());

src/lib.rs

@@ -2,8 +2,8 @@
 
 pub(crate) mod bin_target;
 pub mod build;
-pub mod config;
-pub mod external_cli;
+pub(crate) mod config;
+pub(crate) mod external_cli;
 pub mod lint;
 pub mod run;
 pub mod template;

src/lint.rs

@@ -1,3 +1,5 @@
+//! Helper functions to run `bevy_lint`.
+
 use anyhow::{Context, anyhow, ensure};
 use std::{env, path::PathBuf};
 

src/run/mod.rs

@@ -1,3 +1,5 @@
+//! Provides functionalities to run a Bevy app targeting either native or web platforms.
+
 #[cfg(feature = "web")]
 use crate::web::run::run_web;
 use crate::{bin_target::select_run_binary, config::CliConfig, external_cli::cargo};
@@ -6,6 +8,11 @@ pub use self::args::RunArgs;
 
 pub mod args;
 
+/// Tries to run the project with the given [`RunArgs`].
+///
+/// # Errors
+///
+/// will error if the build process can not be completed
 pub fn run(args: &mut RunArgs) -> anyhow::Result<()> {
     let metadata = cargo::metadata::metadata()?;
 

src/template.rs

@@ -1,3 +1,5 @@
+//! Utilities to create a new Bevy project with `cargo-generate`
+
 use cargo_generate::{GenerateArgs, TemplatePath};
 use regex::Regex;
 use reqwest::blocking::Client;