Improve docs (#899)

* feat: Make try_from private

* docs: Improve docs

* feat: Make erase_parts private

* docs: Improve docs

* docs: Fix typos

Author: SergioGasquez

CHANGELOG.md

@@ -17,24 +17,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add `--monitor` option to `write-bin`. (#783)
 - Add `watchdog-reset` strategy to `--after` subcommand (#779)
 - Add `ROM` version of `read-flash` command (#812)
-- `espflash` can detect the log format automatically from ESP-HAL metadata. Reqires `esp-println` 0.14 (presumably, yet to be released) (#809)
+- `espflash` can detect the log format automatically from ESP-HAL metadata. Requires `esp-println` 0.14 (presumably, yet to be released) (#809)
 - Add `--output-format` option to monitor (#818)
 - Added chip detection based on security info, where supported (#814)
-- `espflash` can detect the chip from ESP-HAL metadata to prevent flashing firmware built for a different device. Reqires `esp-hal` 1.0.0-beta.0 (presumably, yet to be released) (#816)
+- `espflash` can detect the chip from ESP-HAL metadata to prevent flashing firmware built for a different device. Requires `esp-hal` 1.0.0-beta.0 (presumably, yet to be released) (#816)
 - `espflash` no longer allows flashing a too-big partition table (#830)
 - Allow specifying a partition label for `write-bin`, add `--partition-table`. (#828)
 - `--mmu-page-size` parameter for `flash` and `save-image` (#835)
 - Run some arguments checks for monitoring flags. (#842)
 - Add support for the ESP32-C5 (#863)
 - `--after` options now work with `espflash board-info`, `espflash read-flash` and `espflash checksum-md5` (#867)
 - Add support for serial port configuration files. (#777, #883)
-- Add a `check-app-descriptor` bool option to `ImageArgs` and add the flag to `flash` commad(#872)
+- Add a `check-app-descriptor` bool option to `ImageArgs` and add the flag to `flash` command (#872)
 - `Connection::into_serial` to get the underlying port from the connection (#882)
 - All methods on the now removed `Target` & `ReadEFuse`, `UsbOtg` and `RtcWdtReset` traits have been implemented directly on (#891)
 
 ### Changed
 
-- Split the baudrate for connecting and monitorinig in `flash` subcommand (#737)
+- Split the baudrate for connecting and monitoring in `flash` subcommand (#737)
 - Normalized arguments of the CLI commands (#759)
 - `board-info` now prints `Security information`. (#758)
 - The `command`, `elf` and `error` modules are no longer public (#772)
@@ -72,7 +72,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix `read-flash` which didn't work with some lengths (#804)
 - espflash can now flash an ESP32-S2 in download mode over USB (#813)
 - Fixed a case where esplash transformed the firmware elf in a way that made it unbootable (#831)
-- The app descriptor is now correctly placed in the front of the bianry (#835)
+- The app descriptor is now correctly placed in the front of the binary (#835)
 - espflash now extracts the MMU page size from the app descriptor (#835)
 - `ResetBeforeOperation` & `ResetAfterOperation` are now public, to allow the creation of a `Connection` (#895)
 

cargo-espflash/src/cargo_config.rs

@@ -8,18 +8,21 @@ use serde::Deserialize;
 
 use crate::error::TomlError;
 
+/// Unstable features.
 #[derive(Debug, Default, Deserialize)]
 #[serde(rename_all = "kebab-case")]
 pub struct Unstable {
     #[serde(default)]
     build_std: Vec<String>,
 }
 
+/// Build configuration extracted from `.cargo/config.toml`.
 #[derive(Debug, Default, Deserialize)]
 pub struct Build {
     target: Option<String>,
 }
 
+/// Representation of a Cargo configuration extracted from `.cargo/config.toml`.
 #[derive(Debug, Deserialize, Default)]
 pub struct CargoConfig {
     #[serde(default)]
@@ -29,6 +32,8 @@ pub struct CargoConfig {
 }
 
 impl CargoConfig {
+    /// Load and merge Cargo configuration from the workspace and/or package
+    /// level.
     pub fn load(workspace_root: &Path, package_root: &Path) -> Self {
         // If there is a Cargo configuration file in the current package, we will
         // deserialize and return it.
@@ -44,10 +49,12 @@ impl CargoConfig {
         }
     }
 
+    /// Returns if the build has unstable `build-std` feature enabled.
     pub fn has_build_std(&self) -> bool {
         !self.unstable.build_std.is_empty()
     }
 
+    /// Returns the build `target` specified in the configuration, if any.
     pub fn target(&self) -> Option<&str> {
         self.build.target.as_deref()
     }

cargo-espflash/src/error.rs

@@ -7,6 +7,7 @@ use espflash::target::Chip;
 use miette::{Diagnostic, LabeledSpan, SourceCode};
 use thiserror::Error;
 
+/// Error type returned by `cargo-espflash`.
 #[derive(Debug, Diagnostic, Error)]
 #[non_exhaustive]
 pub enum Error {
@@ -64,6 +65,7 @@ pub struct TomlError {
 }
 
 impl TomlError {
+    /// Create a new [`TomlError`] from the raw `toml`.
     pub fn new(err: toml::de::Error, source: String) -> Self {
         Self { err, source }
     }
@@ -104,6 +106,7 @@ pub struct UnsupportedTargetError {
 }
 
 impl UnsupportedTargetError {
+    /// Construct a new [`UnsupportedTargetError`].
     pub fn new(target: &str, chip: Chip) -> Self {
         Self {
             target: target.into(),
@@ -124,6 +127,7 @@ pub struct NoTargetError {
 }
 
 impl NoTargetError {
+    /// Create a new [`NoTargetError`].
     pub fn new(chip: Option<Chip>) -> Self {
         Self { chip }
     }

cargo-espflash/src/main.rs

@@ -94,7 +94,7 @@ enum Commands {
     /// 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
+    /// <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/app_image_format.html>
     Flash(FlashArgs),
     /// Hold the target device in reset
     HoldInReset(ConnectArgs),
@@ -110,7 +110,7 @@ enum Commands {
     /// 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
+    /// <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
@@ -229,7 +229,7 @@ fn main() -> Result<()> {
     miette::set_panic_hook();
     initialize_logger(LevelFilter::Info);
 
-    // Attempt to parse any provided comand-line arguments, or print the help
+    // Attempt to parse any provided command-line arguments, or print the help
     // message and terminate if the invocation is not correct.
     let cli = Cli::parse();
     let CargoSubcommand::Espflash {
@@ -276,7 +276,7 @@ struct BuildContext {
     pub partition_table_path: Option<PathBuf>,
 }
 
-pub fn erase_parts(args: ErasePartsArgs, config: &Config) -> Result<()> {
+fn erase_parts(args: ErasePartsArgs, config: &Config) -> Result<()> {
     if args.connect_args.no_stub {
         return Err(EspflashError::StubRequired).into_diagnostic();
     }

cargo-espflash/src/package_metadata.rs

@@ -6,13 +6,18 @@ use serde::Deserialize;
 
 use crate::error::Error;
 
+/// Package metadata.
 #[derive(Debug, Default, Clone, Deserialize)]
 pub struct PackageMetadata {
+    /// Path to the root of the Cargo workspace the package belongs to.
     pub workspace_root: PathBuf,
+    /// Path to the directory that contains the `Cargo.toml` for the
+    /// selected package.
     pub package_root: PathBuf,
 }
 
 impl PackageMetadata {
+    /// Load package metadata.
     pub fn load(package_name: &Option<String>) -> Result<Self> {
         // There MUST be a cargo manifest in the executing directory, regardless of
         // whether or not we are in a workspace.

espflash/src/bin/espflash.rs

@@ -22,6 +22,7 @@ use espflash::{
 use log::{LevelFilter, debug, info};
 use miette::{IntoDiagnostic, Result, WrapErr};
 
+/// Main CLI parser.
 #[derive(Debug, Parser)]
 #[command(about, max_term_width = 100, propagate_version = true, version)]
 pub struct Cli {
@@ -65,7 +66,7 @@ enum Commands {
     /// 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
+    /// <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/app_image_format.html>
     Flash(FlashArgs),
     /// Hold the target device in reset
     HoldInReset(ConnectArgs),
@@ -81,7 +82,7 @@ enum Commands {
     /// 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
+    /// <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
@@ -200,7 +201,7 @@ fn main() -> Result<()> {
     }
 }
 
-pub fn erase_parts(args: ErasePartsArgs, config: &Config) -> Result<()> {
+fn erase_parts(args: ErasePartsArgs, config: &Config) -> Result<()> {
     if args.connect_args.no_stub {
         return Err(Error::StubRequired.into());
     }

espflash/src/cli/mod.rs

@@ -339,6 +339,7 @@ pub struct ChecksumMd5Args {
     connect_args: ConnectArgs,
 }
 
+/// List the available serial ports.
 #[derive(Debug, Args)]
 #[non_exhaustive]
 pub struct ListPortsArgs {
@@ -490,6 +491,7 @@ pub fn checksum_md5(args: &ChecksumMd5Args, config: &Config) -> Result<()> {
     Ok(())
 }
 
+/// List the available serial ports.
 pub fn list_ports(args: &ListPortsArgs, config: &PortConfig) -> Result<()> {
     let mut ports: Vec<SerialPortInfo> = serial::detect_usb_serial_ports(true)?
         .into_iter()
@@ -1141,6 +1143,7 @@ pub fn write_bin(args: WriteBinArgs, config: &Config) -> Result<()> {
     Ok(())
 }
 
+/// Reset the target device.
 pub fn reset(args: ConnectArgs, config: &Config) -> Result<()> {
     let mut args = args.clone();
     args.no_stub = true;
@@ -1151,13 +1154,15 @@ pub fn reset(args: ConnectArgs, config: &Config) -> Result<()> {
     Ok(())
 }
 
+/// Hold the target device in reset.
 pub fn hold_in_reset(args: ConnectArgs, config: &Config) -> Result<()> {
     connect(&args, config, true, true)?;
     info!("Holding target device in reset");
 
     Ok(())
 }
 
+/// Ensures the chip is compatible with the ELF file.
 pub fn ensure_chip_compatibility(chip: Chip, elf: Option<&[u8]>) -> Result<()> {
     let metadata = Metadata::from_bytes(elf);
     let Some(elf_chip) = metadata.chip_name() else {

espflash/src/cli/monitor/mod.rs

@@ -262,6 +262,7 @@ fn handle_key_event(key_event: KeyEvent) -> Option<Vec<u8>> {
     key_str.map(|slice| slice.into())
 }
 
+/// Checks the monitor arguments and emits warnings if they are invalid.
 pub fn check_monitor_args(monitor: &bool, monitor_args: &MonitorConfigArgs) -> Result<()> {
     // Check if any monitor args are provided but monitor flag isn't set
     if !monitor

espflash/src/cli/monitor/parser/esp_defmt.rs

@@ -203,6 +203,7 @@ impl DefmtData {
     }
 }
 
+/// A parser for defmt-encoded data.
 pub struct EspDefmt {
     delimiter: FrameDelimiter,
     defmt_data: DefmtData,
@@ -215,6 +216,7 @@ impl std::fmt::Debug for EspDefmt {
 }
 
 impl EspDefmt {
+    /// Creates a new `EspDefmt` parser.
     pub fn new(elf: Option<&[u8]>, output_format: Option<String>) -> Result<Self> {
         DefmtData::load(elf, output_format).map(|defmt_data| Self {
             delimiter: FrameDelimiter::new(),

espflash/src/cli/monitor/parser/mod.rs

@@ -13,6 +13,7 @@ pub mod serial;
 
 /// Trait for parsing input data.
 pub trait InputParser {
+    /// Feeds the parser with new data.
     fn feed(&mut self, bytes: &[u8], out: &mut dyn Write);
 }