Fix a number of spelling errors in the documentation (#433)

* Add missing doc comments for error types

* Fix a number of spelling errors in the documentation

* Minor improvements to errors

* Capitalize acronyms

Author: jessebraham

cargo-espflash/src/error.rs

@@ -21,7 +21,7 @@ pub enum Error {
     #[error("The current workspace is invalid, and could not be loaded")]
     #[diagnostic(
         code(cargo_espflash::invalid_workspace),
-        help("Ensure that a valid Cargo.toml file is in the executing directory")
+        help("Ensure that a valid `Cargo.toml` file is in the executing directory")
     )]
     InvalidWorkspace,
 
@@ -45,9 +45,9 @@ pub enum Error {
         code(cargo_espflash::no_build_std),
         help(
             "Cargo currently requires the unstable 'build-std' feature, ensure \
-            that .cargo/config{{.toml}} has the appropriate options.\n  \
-            \tSee: https://doc.rust-lang.org/cargo/reference/unstable.html#build-std"
-        )
+            that `.cargo/config{{.toml}}` has the appropriate options."
+        ),
+        url("https://doc.rust-lang.org/cargo/reference/unstable.html#build-std")
     )]
     NoBuildStd,
 
@@ -59,7 +59,7 @@ pub enum Error {
     )]
     NoPackage,
 
-    #[error("No Cargo.toml found in the current directory")]
+    #[error("No `Cargo.toml` found in the current directory")]
     #[diagnostic(
         code(cargo_espflash::no_project),
         help("Ensure that you're running the command from within a Cargo project")

espflash/src/cli/config.rs

@@ -82,13 +82,13 @@ pub struct Config {
     /// Preferred USB devices
     #[serde(default)]
     pub usb_device: Vec<UsbDevice>,
-    /// Path of the file to save the config to
+    /// Path of the file to save the configuration to
     #[serde(skip)]
     save_path: PathBuf,
 }
 
 impl Config {
-    /// Load the config from config file
+    /// Load configuration from the configuration file
     pub fn load() -> Result<Self> {
         let dirs = ProjectDirs::from("rs", "esp", "espflash").unwrap();
         let file = dirs.config_dir().join("espflash.toml");
@@ -102,7 +102,7 @@ impl Config {
         Ok(config)
     }
 
-    /// Save the config to the config file
+    /// Save configuration to the configuration file
     pub fn save_with<F: Fn(&mut Self)>(&self, modify_fn: F) -> Result<()> {
         let mut copy = self.clone();
         modify_fn(&mut copy);

espflash/src/cli/mod.rs

@@ -120,7 +120,7 @@ pub struct PartitionTableArgs {
     /// Input partition table
     #[arg(value_name = "FILE")]
     partition_table: PathBuf,
-    /// Convert CSV parition table to binary representation
+    /// Convert CSV partition table to binary representation
     #[arg(long, conflicts_with = "to_csv")]
     to_binary: bool,
     /// Convert binary partition table to CSV representation

espflash/src/cli/serial.rs

@@ -104,8 +104,8 @@ fn find_serial_port(ports: &[SerialPortInfo], name: &str) -> Result<SerialPortIn
     }
 }
 
-/// Serialport's autodetect doesn't provide any port information when using musl
-/// linux we can do some manual parsing of sysfs to get the relevant bits
+/// Serialport's auto-detect doesn't provide any port information when using MUSL
+/// Linux we can do some manual parsing of sysfs to get the relevant bits
 /// without udev
 #[cfg(all(target_os = "linux", target_env = "musl"))]
 fn detect_usb_serial_ports() -> Result<Vec<SerialPortInfo>> {
@@ -186,7 +186,7 @@ fn detect_usb_serial_ports() -> Result<Vec<SerialPortInfo>> {
     Ok(ports)
 }
 
-/// USB UART adapters which are known to be on common dev boards
+/// USB UART adapters which are known to be on common development boards
 const KNOWN_DEVICES: &[UsbDevice] = &[
     UsbDevice {
         vid: 0x10c4,

espflash/src/connection.rs

@@ -164,14 +164,14 @@ impl Connection {
         Ok(())
     }
 
-    /// Set baudrate for the serial port
+    /// Set baud rate for the serial port
     pub fn set_baud(&mut self, speed: u32) -> Result<(), Error> {
         self.serial.serial_port_mut().set_baud_rate(speed)?;
 
         Ok(())
     }
 
-    /// Get the current baudrate of the serial port
+    /// Get the current baud rate of the serial port
     pub fn get_baud(&self) -> Result<u32, Error> {
         Ok(self.serial.serial_port().baud_rate()?)
     }

espflash/src/error.rs

@@ -18,6 +18,7 @@ use crate::{
     targets::Chip,
 };
 
+/// All possible errors returned by espflash
 #[derive(Debug, Diagnostic, Error)]
 #[non_exhaustive]
 pub enum Error {
@@ -172,6 +173,7 @@ impl From<SerialConfigError> for Error {
     }
 }
 
+/// Connection-related errors
 #[derive(Debug, Diagnostic, Error)]
 #[non_exhaustive]
 pub enum ConnectionError {
@@ -253,6 +255,7 @@ impl From<SlipError> for ConnectionError {
     }
 }
 
+/// An executed command which has timed out
 #[derive(Clone, Debug, Default)]
 pub struct TimedOutCommand {
     command: Option<CommandType>,
@@ -273,6 +276,7 @@ impl From<CommandType> for TimedOutCommand {
     }
 }
 
+/// Errors originating from a device's ROM functionality
 #[derive(Clone, Copy, Debug, Default, Diagnostic, Error, FromRepr)]
 #[non_exhaustive]
 #[repr(u8)]
@@ -357,6 +361,7 @@ impl From<u8> for RomErrorKind {
     }
 }
 
+/// An error originating from a device's ROM functionality
 #[derive(Clone, Copy, Debug, Diagnostic, Error)]
 #[error("Error while running {command} command")]
 #[non_exhaustive]
@@ -372,6 +377,7 @@ impl RomError {
     }
 }
 
+/// Missing partition error
 #[derive(Debug, Diagnostic, Error)]
 #[error("Missing partition")]
 #[diagnostic(
@@ -386,6 +392,7 @@ impl From<String> for MissingPartition {
     }
 }
 
+/// Missing partition table error
 #[derive(Debug, Error, Diagnostic)]
 #[error("No partition table could be found")]
 #[diagnostic(
@@ -394,6 +401,7 @@ impl From<String> for MissingPartition {
 )]
 pub struct MissingPartitionTable;
 
+/// Invalid ELF file error
 #[derive(Debug, Error)]
 #[error("{0}")]
 pub struct ElfError(&'static str);
@@ -404,7 +412,7 @@ impl From<&'static str> for ElfError {
     }
 }
 
-/// Uunsuported image format error
+/// Unsupported image format error
 #[derive(Debug)]
 pub struct UnsupportedImageFormatError {
     format: ImageFormatKind,
@@ -434,7 +442,7 @@ impl UnsupportedImageFormatError {
             .join(", ")
     }
 
-    /// Update the context of the unsported image format error
+    /// Update the context of the unsupported image format error
     pub fn with_context(mut self, ctx: String) -> Self {
         self.context.replace(ctx);
 

espflash/src/flasher/mod.rs

@@ -139,7 +139,7 @@ impl FlashSize {
     /// Encodes flash size into the format used by the bootloader.
     ///
     /// ## Values:
-    /// * [Esp8266](https://docs.espressif.com/projects/esptool/en/latest/esp8266/advanced-topics/firmware-image-format.html#file-header)
+    /// * [ESP8266](https://docs.espressif.com/projects/esptool/en/latest/esp8266/advanced-topics/firmware-image-format.html#file-header)
     /// * [Others](https://docs.espressif.com/projects/esptool/en/latest/esp32s3/advanced-topics/firmware-image-format.html#file-header)
     pub const fn encode_flash_size(self: FlashSize, chip: Chip) -> Result<u8, Error> {
         use FlashSize::*;
@@ -280,7 +280,7 @@ impl SpiAttachParams {
     }
 }
 
-/// List of spi params to try while detecting flash size
+/// List of SPI parameters to try while detecting flash size
 const TRY_SPI_PARAMS: [SpiAttachParams; 2] =
     [SpiAttachParams::default(), SpiAttachParams::esp32_pico_d4()];
 
@@ -333,7 +333,7 @@ pub trait ProgressCallbacks {
     fn init(&mut self, addr: u32, total: usize);
     /// Update some progress report
     fn update(&mut self, current: usize);
-    /// Finish some prgoress report
+    /// Finish some progress report
     fn finish(&mut self);
 }
 
@@ -686,7 +686,7 @@ impl Flasher {
         Ok(info)
     }
 
-    /// Load an elf image to ram and execute it
+    /// Load an ELF image to RAM and execute it
     ///
     /// Note that this will not touch the flash on the device
     pub fn load_elf_to_ram(
@@ -716,7 +716,7 @@ impl Flasher {
         target.finish(&mut self.connection, true).flashing()
     }
 
-    /// Load an elf image to flash and execute it
+    /// Load an ELF image to flash and execute it
     pub fn load_elf_to_flash_with_format(
         &mut self,
         elf_data: &[u8],
@@ -756,7 +756,7 @@ impl Flasher {
             flash_freq,
         )?;
 
-        // When the "cli" feature is enabled, display the image size information.
+        // When the `cli` feature is enabled, display the image size information.
         #[cfg(feature = "cli")]
         crate::cli::display_image_size(image.app_size(), image.part_size());
 
@@ -791,7 +791,7 @@ impl Flasher {
         Ok(())
     }
 
-    /// Load an elf image to flash and execute it
+    /// Load an ELF image to flash and execute it
     pub fn load_elf_to_flash(
         &mut self,
         elf_data: &[u8],

espflash/src/flasher/stubs.rs

@@ -8,7 +8,7 @@ use crate::targets::Chip;
 pub struct FlashStub {
     /// Entry point (address)
     entry: u32,
-    /// Text (b64 encoded)
+    /// Text (base64 encoded)
     text: String,
     /// Start of text section address
     text_start: u32,

espflash/src/image_format/idf_bootloader.rs

@@ -213,11 +213,11 @@ impl<'a> ImageFormat<'a> for IdfBootloaderFormat<'a> {
 }
 
 /// Actual alignment (in data bytes) required for a segment header: positioned
-/// so that after we write the next 8 byte header, file_offs % IROM_ALIGN ==
+/// so that after we write the next 8 byte header, file_offset % IROM_ALIGN ==
 /// segment.addr % IROM_ALIGN
 ///
 /// (this is because the segment's vaddr may not be IROM_ALIGNed, more likely is
-/// aligned IROM_ALIGN+0x18 to account for the binary file header
+/// aligned IROM_ALIGN+0x18 to account for the binary file header)
 fn get_segment_padding(offset: usize, segment: &CodeSegment) -> u32 {
     let align_past = (segment.addr - SEG_HEADER_LEN) % IROM_ALIGN;
     let pad_len = ((IROM_ALIGN - ((offset as u32) % IROM_ALIGN)) + align_past) % IROM_ALIGN;

espflash/src/image_format/mod.rs

@@ -117,12 +117,12 @@ struct SegmentHeader {
 
 /// Operations for working with firmware image formats
 pub trait ImageFormat<'a>: Send {
-    /// Get the rom segments needed when flashing to device
+    /// Get the ROM segments needed when flashing to device
     fn flash_segments<'b>(&'b self) -> Box<dyn Iterator<Item = RomSegment<'b>> + 'b>
     where
         'a: 'b;
 
-    /// Get the rom segments to save when exporting for ota
+    /// Get the ROM segments to save when exporting for OTA
     ///
     /// Compared to `flash_segments` this excludes things like bootloader and
     /// partition table

espflash/src/lib.rs

@@ -58,7 +58,7 @@ pub mod image_format;
 pub mod interface;
 pub mod targets;
 
-/// Logging utilties
+/// Logging utilities
 #[cfg(feature = "cli")]
 #[cfg_attr(docsrs, doc(cfg(feature = "cli")))]
 pub mod logging {

espflash/src/targets/esp32s2.rs

@@ -57,7 +57,7 @@ impl Esp32s2 {
         Ok(flash_version)
     }
 
-    /// Return the psram version based on eFuses
+    /// Return the PSRAM version based on eFuses
     fn get_psram_version(&self, connection: &mut Connection) -> Result<u32, Error> {
         let blk1_word3 = self.read_efuse(connection, 20)?;
         let psram_version = (blk1_word3 >> 28) & 0xf;

espflash/src/targets/mod.rs

@@ -44,7 +44,7 @@ mod esp32s3;
 mod esp8266;
 mod flash_target;
 
-/// Enumeration of all supported devices
+/// All supported devices
 #[cfg_attr(feature = "cli", derive(clap::ValueEnum))]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Display, EnumIter, EnumString, EnumVariantNames)]
 #[non_exhaustive]
@@ -165,8 +165,9 @@ impl Esp32Params {
     }
 
     /// Generates a default partition table.
+    ///
     /// `flash_size` is used to scale app partition when present, otherwise the
-    /// param defaults are used.
+    /// paramameter defaults are used.
     pub fn default_partition_table(&self, flash_size: Option<u32>) -> PartitionTable {
         PartitionTable::new(vec![
             Partition::new(
@@ -261,7 +262,7 @@ pub trait Target: ReadEFuse {
     /// Enumerate the chip's features, read from eFuse
     fn chip_features(&self, connection: &mut Connection) -> Result<Vec<&str>, Error>;
 
-    /// Deterimine the chip's revision number
+    /// Determine the chip's revision number
     fn chip_revision(&self, connection: &mut Connection) -> Result<(u32, u32), Error> {
         let major = self.major_chip_version(connection)?;
         let minor = self.minor_chip_version(connection)?;