Minor docs improvement (#878)

* Minor docs improvement

* Add a forgotten one

* add periods

Author: JurajSadel

espflash/src/cli/mod.rs

@@ -208,29 +208,31 @@ pub struct ReadFlashArgs {
     pub max_in_flight: u32,
 }
 
-/// Save the image to disk instead of flashing to device
+/// Save the image to disk instead of flashing to device.
 #[derive(Debug, Args)]
 #[non_exhaustive]
 #[group(skip)]
 pub struct SaveImageArgs {
-    /// Chip to create an image for
+    /// Chip to create an image for.
     #[arg(long, value_enum)]
     pub chip: Chip,
-    /// File name to save the generated image to
+    /// File name to save the generated image to.
     pub file: PathBuf,
-    /// Boolean flag to merge binaries into single binary
+    /// Boolean flag to merge binaries into single binary.
     #[arg(long)]
     pub merge: bool,
-    /// Don't pad the image to the flash size
+    /// Don't pad the image to the flash size.
     #[arg(long, requires = "merge")]
     pub skip_padding: bool,
-    /// Cristal frequency of the target
+    /// Crystal frequency of the target.
     #[arg(long, short = 'x')]
     pub xtal_freq: Option<XtalFrequency>,
     #[clap(flatten)]
+    /// Image arguments.
     pub image: ImageArgs,
 }
 
+/// Image arguments needed for image generation.
 #[derive(Debug, Args)]
 #[non_exhaustive]
 #[group(skip)]
@@ -258,6 +260,7 @@ pub struct ImageArgs {
     pub check_app_descriptor: Option<bool>,
 }
 
+/// Arguments for connection and monitoring
 #[derive(Debug, Args)]
 #[non_exhaustive]
 pub struct MonitorArgs {
@@ -300,6 +303,7 @@ pub struct MonitorConfigArgs {
     processors: Option<String>,
 }
 
+/// Arguments for MD5 checksum calculation
 #[derive(Debug, Args)]
 #[non_exhaustive]
 pub struct ChecksumMd5Args {
@@ -757,6 +761,7 @@ impl ProgressCallbacks for EspflashProgress {
     }
 }
 
+/// Erase the entire flash memory of a target device
 pub fn erase_flash(args: EraseFlashArgs, config: &Config) -> Result<()> {
     if args.connect_args.no_stub {
         return Err(Error::StubRequired.into());
@@ -777,6 +782,7 @@ pub fn erase_flash(args: EraseFlashArgs, config: &Config) -> Result<()> {
     Ok(())
 }
 
+/// Erase a specified region of flash memory
 pub fn erase_region(args: EraseRegionArgs, config: &Config) -> Result<()> {
     if args.connect_args.no_stub {
         return Err(Error::StubRequired).into_diagnostic();
@@ -1016,6 +1022,7 @@ fn pretty_print(table: PartitionTable) {
     println!("{pretty}");
 }
 
+/// Creates `FlashData` from `ImageArgs`, `FlashConfigArgs`, and `Config`.
 pub fn make_flash_data(
     image_args: ImageArgs,
     flash_config_args: &FlashConfigArgs,

espflash/src/cli/monitor/external_processors.rs

@@ -57,6 +57,7 @@ use std::{
 
 use miette::Diagnostic;
 
+/// Represents an error associated with a specific executable.
 #[derive(Debug)]
 pub struct Error {
     executable: String,
@@ -80,6 +81,7 @@ struct Processor {
 }
 
 impl Processor {
+    /// Creates a new processor from a child process.
     pub fn new(child: Child) -> Self {
         let mut child = child;
         let (tx, rx) = mpsc::channel::<u8>();
@@ -103,6 +105,7 @@ impl Processor {
         Self { rx, stdin, child }
     }
 
+    /// Tries to receive data from the processor.
     pub fn try_receive(&mut self) -> Vec<u8> {
         let mut res = Vec::new();
         while let Ok(b) = self.rx.try_recv() {
@@ -111,6 +114,7 @@ impl Processor {
         res
     }
 
+    /// Sends data to the processor.
     pub fn send(&mut self, data: Vec<u8>) {
         let _ignored = self.stdin.write(&data).ok();
     }
@@ -122,12 +126,14 @@ impl Drop for Processor {
     }
 }
 
+/// Represents a collection of external processors.
 #[derive(Debug)]
 pub struct ExternalProcessors {
     processors: Vec<Processor>,
 }
 
 impl ExternalProcessors {
+    /// Creates a new collection of external processors.
     pub fn new(processors: Option<String>, elf: Option<PathBuf>) -> Result<Self, Error> {
         let mut args = Vec::new();
 
@@ -156,6 +162,8 @@ impl ExternalProcessors {
         })
     }
 
+    /// Processes input bytes through a series of processors, returning the
+    /// final output.
     pub fn process(&mut self, read: &[u8]) -> Vec<u8> {
         let mut buffer = Vec::new();
         buffer.extend_from_slice(read);

espflash/src/cli/monitor/line_endings.rs

@@ -35,6 +35,7 @@ where
     }
 }
 
+/// Normalize line endings to CRLF.
 pub(crate) fn normalized(iter: impl Iterator<Item = u8>) -> impl Iterator<Item = u8> {
     Normalized {
         iter,

espflash/src/cli/monitor/mod.rs

@@ -41,6 +41,7 @@ pub mod parser;
 mod line_endings;
 mod symbols;
 
+/// Log format to use when parsing incoming data.
 #[cfg_attr(feature = "cli", derive(clap::ValueEnum))]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Display, EnumIter, EnumString, VariantNames)]
 #[non_exhaustive]
@@ -56,6 +57,7 @@ pub enum LogFormat {
 struct RawModeGuard;
 
 impl RawModeGuard {
+    /// Enable raw mode and return a guard that will disable it when dropped.
     pub fn new() -> Result<Self> {
         enable_raw_mode().into_diagnostic()?;
         Ok(RawModeGuard)

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

@@ -12,6 +12,7 @@ use thiserror::Error;
 
 use crate::cli::monitor::parser::InputParser;
 
+/// Errors that can occur when setting up the defmt logger.
 #[derive(Clone, Copy, Debug, Diagnostic, Error)]
 #[error("Could not set up defmt logger")]
 pub enum DefmtError {
@@ -79,6 +80,8 @@ impl FrameDelimiter {
         Some((&haystack[start..][..end], start + end + needle.len()))
     }
 
+    /// Feeds data into the parser, extracting and processing framed or raw
+    /// data.
     pub fn feed(&mut self, buffer: &[u8], mut process: impl FnMut(FrameKind<'_>)) {
         self.buffer.extend_from_slice(buffer);
 

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

@@ -11,6 +11,7 @@ use crate::cli::monitor::{line_endings::normalized, symbols::Symbols};
 pub mod esp_defmt;
 pub mod serial;
 
+/// Trait for parsing input data.
 pub trait InputParser {
     fn feed(&mut self, bytes: &[u8], out: &mut dyn Write);
 }
@@ -102,6 +103,7 @@ impl Utf8Merger {
     }
 }
 
+/// A printer that resolves symbol names and writes formatted output.
 #[allow(missing_debug_implementations)]
 pub struct ResolvingPrinter<'ctx, W: Write> {
     writer: W,
@@ -111,6 +113,7 @@ pub struct ResolvingPrinter<'ctx, W: Write> {
 }
 
 impl<'ctx, W: Write> ResolvingPrinter<'ctx, W> {
+    /// Creates a new `ResolvingPrinter` with the given ELF file and writer.
     pub fn new(elf: Option<&'ctx [u8]>, writer: W) -> Self {
         Self {
             writer,

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

@@ -2,6 +2,7 @@ use std::io::Write;
 
 use crate::cli::monitor::parser::InputParser;
 
+/// Serial parser.
 #[derive(Debug)]
 pub struct Serial;
 

espflash/src/cli/monitor/symbols.rs

@@ -15,6 +15,7 @@ pub(crate) struct Symbols<'sym> {
 }
 
 impl<'sym> Symbols<'sym> {
+    /// Tries to create a new `Symbols` instance from the given ELF file bytes.
     pub fn try_from(bytes: &'sym [u8]) -> Result<Self, Box<dyn Error>> {
         let object = File::parse(bytes)?;
         let dwarf = Dwarf::load(