refactor(map): clean map iterator api, add docs

Signed-off-by: Haobo Gu <[email protected]>

Cargo.toml

@@ -31,8 +31,6 @@ std = []
 arrayvec = ["dep:arrayvec"]
 alloc = []
 heapless = ["dep:heapless"]
-# Enable the raw access of items. This feature is NOT bounded by the semver.
-raw_access = []
 _test = ["dep:futures", "dep:approx", "std", "arrayvec", "alloc", "heapless"]
 
 [lints.rust]

src/map.rs

@@ -111,7 +111,27 @@ use self::{
 
 use super::*;
 
-/// Iterator which iterates all valid items
+/// Iterator which iterates all non-erased & non-corrupted items in the map.
+///
+/// The iterator will return the (Key, Value) tuple when calling `next()`.
+/// If the iterator ends, it will return `None`.
+///
+/// The following is a simple example of how to use the iterator:
+/// ```rust
+/// // Create the iterator
+/// let mut iterator = get_item_iter(&mut flash, flash_range.clone());
+///
+/// // Iterate through all items
+/// loop {
+///     // Suppose the Key and Value types are u8, u32
+///     if let Ok(Some(item)) = iterator.next::<u8, u32>(&mut buffer).await {
+///          // Do something with the item
+///     } else {
+///         // Iterator ends
+///         break;
+///     }
+/// }
+/// ```
 pub struct MapItemIter<'d, S: NorFlash> {
     flash: &'d mut S,
     flash_range: Range<u32>,
@@ -182,17 +202,6 @@ impl<'d, S: NorFlash> MapItemIter<'d, S> {
     }
 }
 
-/// Get an iterator that iterates over all non-erased & non-corrupted items in the map.
-pub async fn get_next_item<'d, 'a, K: Key, V: Value<'a>, S: NorFlash>(
-    data_buffer: &'a mut [u8],
-    iter: &mut MapItemIter<'d, S>,
-) -> Result<Option<(K, V)>, Error<S::Error>>
-where
-    'd: 'a,
-{
-    iter.next(data_buffer).await
-}
-
 /// Get an iterator that iterates over all non-erased & non-corrupted items in the map.
 pub fn get_item_iter<'d, S: NorFlash>(
     flash: &'d mut S,