Additional docstrings for enums, structs, and traits (#271)

* Document enums and their variants

* Document traits and their functions

* Document structs and their public fields

Author: jessebraham

espflash/src/cli/config.rs

@@ -21,18 +21,23 @@ use serialport::UsbPortInfo;
 /// A configured, known serial connection
 #[derive(Debug, Deserialize, Serialize, Default, Clone)]
 pub struct Connection {
+    /// Name of the serial port used for communication
     pub serial: Option<String>,
-    #[cfg(feature = "raspberry")]
-    pub rts: Option<u8>,
+    /// Data Transmit Ready pin
     #[cfg(feature = "raspberry")]
     pub dtr: Option<u8>,
+    /// Ready To Send pin
+    #[cfg(feature = "raspberry")]
+    pub rts: Option<u8>,
 }
 
 /// A configured, known USB device
 #[derive(Debug, Deserialize, Serialize, Default, Clone)]
 pub struct UsbDevice {
+    /// USB Vendor ID
     #[serde(with = "SerHex::<Compact>")]
     pub vid: u16,
+    /// USB Product ID
     #[serde(with = "SerHex::<Compact>")]
     pub pid: u16,
 }
@@ -46,8 +51,10 @@ impl UsbDevice {
 /// Deserialized contents of a configuration file
 #[derive(Debug, Deserialize, Serialize, Default, Clone)]
 pub struct Config {
+    /// Preferred serial port connection information
     #[serde(default)]
     pub connection: Connection,
+    /// Preferred USB devices
     #[serde(default)]
     pub usb_device: Vec<UsbDevice>,
     #[serde(skip)]

espflash/src/elf.rs

@@ -19,18 +19,26 @@ use crate::{
     targets::Chip,
 };
 
+/// Operations for working with firmware images
 pub trait FirmwareImage<'a> {
+    /// Firmware image entry point
     fn entry(&self) -> u32;
+
+    /// Firmware image segments
     fn segments(&'a self) -> Box<dyn Iterator<Item = CodeSegment<'a>> + 'a>;
+
+    /// Firmware image segments, with their associated load addresses
     fn segments_with_load_addresses(&'a self) -> Box<dyn Iterator<Item = CodeSegment<'a>> + 'a>;
 
+    /// Firmware image ROM segments
     fn rom_segments(&'a self, chip: Chip) -> Box<dyn Iterator<Item = CodeSegment<'a>> + 'a> {
         Box::new(
             self.segments()
                 .filter(move |segment| chip.into_target().addr_is_flash(segment.addr)),
         )
     }
 
+    /// Firmware image RAM segments
     fn ram_segments(&'a self, chip: Chip) -> Box<dyn Iterator<Item = CodeSegment<'a>> + 'a> {
         Box::new(
             self.segments()
@@ -39,6 +47,7 @@ pub trait FirmwareImage<'a> {
     }
 }
 
+/// A firmware image built from an ELF file
 pub struct ElfFirmwareImage<'a> {
     elf: ElfFile<'a>,
 }
@@ -108,8 +117,9 @@ impl<'a> FirmwareImage<'a> for ElfFirmwareImage<'a> {
 }
 
 #[derive(Eq, Clone, Default)]
-/// A segment of code from the source elf
+/// A segment of code from the source ELF
 pub struct CodeSegment<'a> {
+    /// Base address of the code segment
     pub addr: u32,
     data: Cow<'a, [u8]>,
 }
@@ -220,7 +230,9 @@ impl Ord for CodeSegment<'_> {
 #[derive(Clone)]
 /// A segment of data to write to the flash
 pub struct RomSegment<'a> {
+    /// ROM address at which the segment begins
     pub addr: u32,
+    /// Segment data
     pub data: Cow<'a, [u8]>,
 }
 

espflash/src/flasher/mod.rs

@@ -41,26 +41,37 @@ const FLASH_SECTORS_PER_BLOCK: usize = FLASH_SECTOR_SIZE / FLASH_BLOCK_SIZE;
 #[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Display, EnumVariantNames)]
 #[repr(u8)]
 pub enum FlashFrequency {
+    /// 12 MHz
     #[strum(serialize = "12M")]
     Flash12M,
+    /// 15 MHz
     #[strum(serialize = "15M")]
     Flash15M,
+    /// 16 MHz
     #[strum(serialize = "16M")]
     Flash16M,
+    /// 20 MHz
     #[strum(serialize = "20M")]
     Flash20M,
+    /// 24 MHz
     #[strum(serialize = "24M")]
     Flash24M,
+    /// 26 MHz
     #[strum(serialize = "26M")]
     Flash26M,
+    /// 30 MHz
     #[strum(serialize = "30M")]
     Flash30M,
+    /// 40 MHz
     #[strum(serialize = "40M")]
     Flash40M,
+    /// 48 MHz
     #[strum(serialize = "48M")]
     Flash48M,
+    /// 60 MHz
     #[strum(serialize = "60M")]
     Flash60M,
+    /// 80 MHz
     #[strum(serialize = "80M")]
     Flash80M,
 }
@@ -92,9 +103,13 @@ impl FromStr for FlashFrequency {
 #[derive(Copy, Clone, Debug, EnumVariantNames)]
 #[strum(serialize_all = "lowercase")]
 pub enum FlashMode {
+    /// Quad I/O (4 pins used for address & data)
     Qio,
+    /// Quad Output (4 pins used for data)
     Qout,
+    /// Dual I/O (2 pins used for address & data)
     Dio,
+    /// Dual Output (2 pins used for data)
     Dout,
 }
 
@@ -120,24 +135,34 @@ impl FromStr for FlashMode {
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Display, EnumVariantNames)]
 #[repr(u8)]
 pub enum FlashSize {
+    /// 256 KB
     #[strum(serialize = "256K")]
     Flash256Kb = 0x12,
+    /// 512 KB
     #[strum(serialize = "512K")]
     Flash512Kb = 0x13,
+    /// 1 MB
     #[strum(serialize = "1M")]
     Flash1Mb = 0x14,
+    /// 2 MB
     #[strum(serialize = "2M")]
     Flash2Mb = 0x15,
+    /// 4 MB
     #[strum(serialize = "4M")]
     Flash4Mb = 0x16,
+    /// 8 MB
     #[strum(serialize = "8M")]
     Flash8Mb = 0x17,
+    /// 16 MB
     #[strum(serialize = "16M")]
     Flash16Mb = 0x18,
+    /// 32 MB
     #[strum(serialize = "32M")]
     Flash32Mb = 0x19,
+    /// 64 MB
     #[strum(serialize = "64M")]
     Flash64Mb = 0x1a,
+    /// 128 MB
     #[strum(serialize = "128M")]
     Flash128Mb = 0x21,
 }

espflash/src/image_format/mod.rs

@@ -41,6 +41,7 @@ struct SegmentHeader {
     length: u32,
 }
 
+/// Operations for working with firmware image formats
 pub trait ImageFormat<'a>: Send {
     /// Get the rom segments needed when flashing to device
     fn flash_segments<'b>(&'b self) -> Box<dyn Iterator<Item = RomSegment<'b>> + 'b>
@@ -56,13 +57,16 @@ pub trait ImageFormat<'a>: Send {
         'a: 'b;
 }
 
+/// All supported firmware image formats
 #[derive(
     Debug, Copy, Clone, Eq, PartialEq, Display, IntoStaticStr, EnumVariantNames, Deserialize,
 )]
 #[strum(serialize_all = "kebab-case")]
 #[serde(rename_all = "kebab-case")]
 pub enum ImageFormatKind {
+    /// Use the second-stage bootloader from ESP-IDF
     EspBootloader,
+    /// Use direct boot and do not use a second-stage bootloader at all
     DirectBoot,
 }
 

espflash/src/interface.rs

@@ -24,9 +24,12 @@ pub enum SerialConfigError {
 /// Wrapper around SerialPort where platform-specific modifications can be
 /// implemented.
 pub struct Interface {
+    /// Hardware serial port used for communication
     pub serial_port: Box<dyn SerialPort>,
+    /// Data Transmit Ready pin
     #[cfg(feature = "raspberry")]
     pub dtr: Option<OutputPin>,
+    /// Ready To Send pin
     #[cfg(feature = "raspberry")]
     pub rts: Option<OutputPin>,
 }

espflash/src/targets/esp32.rs

@@ -31,6 +31,7 @@ const UART_CLKDIV_MASK: u32 = 0xfffff;
 
 const XTAL_CLK_DIVIDER: u32 = 1;
 
+/// ESP32 Target
 pub struct Esp32;
 
 impl Esp32 {

espflash/src/targets/esp32c2.rs

@@ -29,6 +29,7 @@ const PARAMS: Esp32Params = Esp32Params::new(
     include_bytes!("../../resources/bootloaders/esp32c2-bootloader.bin"),
 );
 
+/// ESP32-C2 Target
 pub struct Esp32c2;
 
 impl Esp32c2 {

espflash/src/targets/esp32c3.rs

@@ -29,6 +29,7 @@ const PARAMS: Esp32Params = Esp32Params::new(
     include_bytes!("../../resources/bootloaders/esp32c3-bootloader.bin"),
 );
 
+/// ESP32-C3 Target
 pub struct Esp32c3;
 
 impl Esp32c3 {

espflash/src/targets/esp32s2.rs

@@ -28,6 +28,7 @@ const PARAMS: Esp32Params = Esp32Params::new(
     include_bytes!("../../resources/bootloaders/esp32s2-bootloader.bin"),
 );
 
+/// ESP32-S2 Target
 pub struct Esp32s2;
 
 impl Esp32s2 {

espflash/src/targets/esp32s3.rs

@@ -26,6 +26,7 @@ const PARAMS: Esp32Params = Esp32Params::new(
     include_bytes!("../../resources/bootloaders/esp32s3-bootloader.bin"),
 );
 
+/// ESP32-S2 Target
 pub struct Esp32s3;
 
 impl Esp32s3 {