From d001db472a31dcb50de091c462148a88e58ed77b Mon Sep 17 00:00:00 2001
From: chrysn <chrysn@fsfe.org>
Date: Wed, 3 Jan 2024 20:01:07 +0100
Subject: [PATCH] doc: Clarify constraints

---
 src/lib.rs       |  5 +++++
 src/nor_flash.rs | 21 ++++++++++++++++-----
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 7c5366a..0ee7888 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -11,6 +11,11 @@
 /// Currently contains [`OverlapIterator`]
 pub mod iter;
 /// Technology specific traits for NOR Flashes
+///
+/// These traits are suitable for NOR flash backed memory, but given the wide range of flash
+/// technologies, not all NOR flashes may implement all those traits, nor <!-- no pun intended -->
+/// will every instance necessarily be backed by NOR flash. The documentation of the individual
+/// traits and their members define the precise criteria for the applicability of the trait.
 pub mod nor_flash;
 
 /// A region denotes a contiguous piece of memory between two addresses.
diff --git a/src/nor_flash.rs b/src/nor_flash.rs
index 447bd1a..dc4a005 100644
--- a/src/nor_flash.rs
+++ b/src/nor_flash.rs
@@ -64,11 +64,13 @@ pub trait ReadNorFlash: ErrorType {
 	///
 	/// # Errors
 	///
-	/// Returns an error if the arguments are not aligned or out of bounds. The implementation
-	/// can use the [`check_read`] helper function.
+	/// Returns an error if the arguments are not aligned, or if the range exceeds the bounds. The
+	/// implementation can use the [`check_read`] helper function.
 	fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error>;
 
 	/// The capacity of the peripheral in bytes.
+	///
+	/// This must be a multiple of READ_SIZE.
 	fn capacity(&self) -> usize;
 }
 
@@ -83,10 +85,12 @@ pub fn check_read<T: ReadNorFlash>(
 
 /// NOR flash trait.
 pub trait NorFlash: ReadNorFlash {
-	/// The minumum number of bytes the storage peripheral can write
+	/// The number of bytes to which writes must be aligned, and of of which written lengths must
+	/// be a multiple of.
 	const WRITE_SIZE: usize;
 
-	/// The minumum number of bytes the storage peripheral can erase
+	/// The number of bytes to which erases must be aligned, and of of which erased lengths must be
+	/// a multiple of.
 	const ERASE_SIZE: usize;
 
 	/// Erase the given storage range, clearing all data within `[from..to]`.
@@ -103,7 +107,8 @@ pub trait NorFlash: ReadNorFlash {
 
 	/// If power is lost during write, the contents of the written words are undefined,
 	/// but the rest of the page is guaranteed to be unchanged.
-	/// It is not allowed to write to the same word twice.
+	/// It is not allowed to write to the same word twice unless another trait
+	/// ([MultiwriteNorFlash]) allows it.
 	///
 	/// # Errors
 	///
@@ -216,7 +221,11 @@ impl Region for Page {
 	}
 }
 
+/// An implementation of byte-addressed [Storage] based on [NorFlash]
 ///
+/// The provided storage is as large as the underlying flash memory, and thus no journaling is
+/// performed. If a write is interrupted, up to a page of data (a size that is not visible to
+/// consumers of the [Storage] trait) may be lost.
 pub struct RmwNorFlashStorage<'a, S> {
 	storage: S,
 	merge_buffer: &'a mut [u8],
@@ -291,7 +300,9 @@ where
 	}
 }
 
+/// An implementation of byte-addressed [Storage] based on [MultiwriteNorFlash]
 ///
+/// Compared to [RmwNorFlashStorage], this may save erases.
 pub struct RmwMultiwriteNorFlashStorage<'a, S> {
 	storage: S,
 	merge_buffer: &'a mut [u8],