Improve FlashStorage documentation

Author: Dark42ed

esp-storage/src/common.rs

@@ -66,6 +66,11 @@ impl<'d> Flash<'d> {
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 /// Flash storage abstraction.
+///
+/// This can write to any location on the SPI Flash. It is recommended
+/// to create a [partition] to store any app data.
+///
+/// [partition]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html
 pub struct FlashStorage<'d> {
     pub(crate) capacity: usize,
     unlocked: bool,

esp-storage/src/nor_flash.rs

@@ -140,6 +140,16 @@ impl NorFlash for FlashStorage<'_> {
     const WRITE_SIZE: usize = Self::WORD_SIZE as _;
     const ERASE_SIZE: usize = Self::SECTOR_SIZE as _;
 
+    /// Writes `bytes` to the flash storage at `offset`.
+    ///
+    /// Requirements:
+    /// - `offset` must be aligned to a word (4 bytes).
+    /// - `bytes.len()` must be a multiple of the word size.
+    /// - The bytes being written to must have been previously erased by [`FlashStorage::erase`].
+    ///
+    /// Requirements not being met will lead to an error or incorrect data being written.
+    ///
+    /// See [`NorFlash::write`] for more information.
     fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Self::Error> {
         const WS: u32 = FlashStorage::WORD_SIZE;
         self.check_alignment::<{ WS }>(offset, bytes.len())?;
@@ -174,6 +184,15 @@ impl NorFlash for FlashStorage<'_> {
         Ok(())
     }
 
+    /// Erases sectors at bytes `[from..to]`
+    ///
+    /// Requirements:
+    /// - `from` must be aligned to a sector (4096 bytes).
+    /// - `to - from` must be a multiple of the sector size.
+    ///
+    /// Requirements not being met will lead to an error.
+    ///
+    /// See [`NorFlash::erase`] for more information.
     fn erase(&mut self, from: u32, to: u32) -> Result<(), Self::Error> {
         let len = (to - from) as _;
         const SZ: u32 = FlashStorage::SECTOR_SIZE;