Add help text for all subcommands (#441)

* Add help text for all subcommands

* Update CHANGELOG

* Fix a typo

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add help text for all subcommands (#441)
+
 ### Fixed
 
 ### Changed

cargo-espflash/Cargo.toml

@@ -26,7 +26,7 @@ pkg-fmt = "zip"
 
 [dependencies]
 cargo_metadata = "0.15.4"
-clap = { version = "4.3.4", features = ["derive"] }
+clap = { version = "4.3.4", features = ["derive", "wrap_help"] }
 env_logger = "0.10.0"
 esp-idf-part = "0.4.1"
 espflash = { version = "=2.0.1-dev", path = "../espflash" }

cargo-espflash/src/main.rs

@@ -32,7 +32,12 @@ mod error;
 mod package_metadata;
 
 #[derive(Debug, Parser)]
-#[clap(bin_name = "cargo", version, propagate_version = true)]
+#[clap(
+    bin_name = "cargo",
+    max_term_width = 100,
+    propagate_version = true,
+    version
+)]
 struct Cli {
     #[clap(subcommand)]
     subcommand: CargoSubcommand,
@@ -49,11 +54,49 @@ enum CargoSubcommand {
 
 #[derive(Debug, Subcommand)]
 enum Commands {
+    /// Print information about a connected target device
+    ///
+    /// Automatically detects and prints the chip type, crystal frequency, flash
+    /// size, chip features, and MAC address of a connected target device.
     BoardInfo(ConnectArgs),
+    /// Generate completions for the given shell
+    ///
+    /// The completions are printed to stdout, and can be redirected as needed.
+    /// The directory in which completion scripts are stored differs
+    /// depending on which shell is being used; consult your shell's
+    /// documentation to determine the appropriate path.
     Completions(CompletionsArgs),
+    /// Flash an application in ELF format to a target device
+    ///
+    /// First convert the ELF file produced by cargo into the appropriate
+    /// binary application image format as required by the ESP32 devices. Once
+    /// we have a valid application image, we can write the bootloader,
+    /// partition table, and application image to the connected target device.
+    ///
+    /// Please refer to the ESP-IDF documentation for more information on the
+    /// binary image format:
+    ///
+    /// https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/app_image_format.html
     Flash(FlashArgs),
+    /// Open the serial monitor without flashing the connected target device
     Monitor(MonitorArgs),
+    /// Convert partition tables between CSV and binary format
+    ///
+    /// Uses the ESP-IDF format for partition tables; please refer to the
+    /// ESP-IDF documentation for more information on this format:
+    ///
+    /// https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html
+    ///
+    /// Allows for conversion between formats via the '--to-csv' and
+    /// '--to-binary' options, plus the ability to print a partition table
+    /// in tabular format.
     PartitionTable(PartitionTableArgs),
+    /// Generate a binary application image and save it to a local disk
+    ///
+    /// If the '--merge' option is used, then the bootloader, partition table,
+    /// and all application segments will be merged into a single binary file.
+    /// Otherwise, each segment will be saved as individual binaries, prefixed
+    /// with their intended addresses in flash.
     SaveImage(SaveImageArgs),
 }
 

espflash/Cargo.toml

@@ -35,7 +35,7 @@ addr2line = { version = "0.20.0", optional = true }
 base64 = "0.21.2"
 binread = "2.2.0"
 bytemuck = { version = "1.13.1", features = ["derive"] }
-clap = { version = "4.3.4", features = ["derive", "env"], optional = true }
+clap = { version = "4.3.4", features = ["derive", "env", "wrap_help"], optional = true }
 clap_complete = { version = "4.3.1", optional = true }
 comfy-table = { version = "7.0.1", optional = true }
 crossterm = { version = "0.25.0", optional = true } # 0.26.x causes issues on Windows
@@ -57,7 +57,7 @@ serde = { version = "1.0.164", features = ["derive"] }
 serialport = "4.2.1"
 sha2 = "0.10.7"
 slip-codec = "0.3.4"
-strum = { version = "0.24.1", features = ["derive"] } # `derive(FromRepr)` broken in 0.25.0
+strum = { version = "0.25.0", features = ["derive"] }
 thiserror = "1.0.40"
 toml = "0.7.4"
 update-informer = { version = "1.0.0", optional = true }

espflash/src/bin/espflash.rs

@@ -22,7 +22,7 @@ use log::{debug, LevelFilter};
 use miette::{IntoDiagnostic, Result, WrapErr};
 
 #[derive(Debug, Parser)]
-#[command(about, version, propagate_version = true)]
+#[command(about, max_term_width = 100, propagate_version = true, version)]
 pub struct Cli {
     #[command(subcommand)]
     subcommand: Commands,
@@ -30,12 +30,51 @@ pub struct Cli {
 
 #[derive(Debug, Subcommand)]
 enum Commands {
+    /// Print information about a connected target device
+    ///
+    /// Automatically detects and prints the chip type, crystal frequency, flash
+    /// size, chip features, and MAC address of a connected target device.
     BoardInfo(ConnectArgs),
+    /// Generate completions for the given shell
+    ///
+    /// The completions are printed to stdout, and can be redirected as needed.
+    /// The directory in which completion scripts are stored differs
+    /// depending on which shell is being used; consult your shell's
+    /// documentation to determine the appropriate path.
     Completions(CompletionsArgs),
+    /// Flash an application in ELF format to a connected target device
+    ///
+    /// Given a path to an ELF file, first convert it into the appropriate
+    /// binary application image format as required by the ESP32 devices. Once
+    /// we have a valid application image, we can write the bootloader,
+    /// partition table, and application image to the connected target device.
+    ///
+    /// Please refer to the ESP-IDF documentation for more information on the
+    /// binary image format:
+    ///
+    /// https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/app_image_format.html
     Flash(FlashArgs),
+    /// Open the serial monitor without flashing the connected target device
     Monitor(MonitorArgs),
+    /// Convert partition tables between CSV and binary format
+    ///
+    /// Uses the ESP-IDF format for partition tables; please refer to the
+    /// ESP-IDF documentation for more information on this format:
+    ///
+    /// https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html
+    ///
+    /// Allows for conversion between formats via the '--to-csv' and
+    /// '--to-binary' options, plus the ability to print a partition table
+    /// in tabular format.
     PartitionTable(PartitionTableArgs),
+    /// Generate a binary application image and save it to a local disk
+    ///
+    /// If the '--merge' option is used, then the bootloader, partition table,
+    /// and all application segments will be merged into a single binary file.
+    /// Otherwise, each segment will be saved as individual binaries, prefixed
+    /// with their intended addresses in flash.
     SaveImage(SaveImageArgs),
+    /// Write a binary file to a specific address in a target device's flash
     WriteBin(WriteBinArgs),
 }