Improve docs around Val conversion in collections

soroban-sdk/src/iter.rs

@@ -1,4 +1,12 @@
 //! Iterators for use with collections like [Map], [Vec].
+//!
+//! Collections are not guaranteed to contain values of the expected type as
+//! they are stored on the host as [Val]s, so two iterators are provided:
+//!
+//! - **`try_iter()`** returns an iterator that yields `Result<T, E>` for each
+//!   element, allowing the caller to handle conversion errors.
+//! - **`iter()`** returns an iterator that unwraps each result,
+//!   panicking if any element cannot be converted to the declared type.
 #[cfg(doc)]
 use crate::{Map, Vec};
 

soroban-sdk/src/map.rs

@@ -53,8 +53,9 @@ macro_rules! map {
 /// converted from [Val] back into their type.
 ///
 /// The pairs of keys and values in a Map are not guaranteed to be of type
-/// `K`/`V` and conversion will fail if they are not. Most functions on Map
-/// return a `Result` due to this.
+/// `K`/`V` and conversion will fail if they are not. Most functions on Map have 
+/// a try_ variation that returns a Result that will be Err if the conversion fails. 
+/// Functions that are not prefixed with try_ will panic if conversion fails."
 ///
 /// There are some cases where this lack of guarantee is important:
 ///
@@ -446,6 +447,9 @@ where
     }
 
     /// Returns a [Vec] of all keys in the map.
+    ///
+    /// This method does not guarantee that the keys are of type `K`. If a key
+    /// exists in the map that is not type `K`, it will be included in the result.
     #[inline(always)]
     pub fn keys(&self) -> Vec<K> {
         let env = self.env();
@@ -454,6 +458,9 @@ where
     }
 
     /// Returns a [Vec] of all values in the map.
+    ///
+    /// This method does not guarantee that the values are of type `V`. If a value
+    /// exists in the map that is not type `V`, it will be included in the result.
     #[inline(always)]
     pub fn values(&self) -> Vec<V> {
         let env = self.env();
@@ -495,6 +502,14 @@ where
     K: IntoVal<Env, Val> + TryFromVal<Env, Val>,
     V: IntoVal<Env, Val> + TryFromVal<Env, Val>,
 {
+    /// Returns an iterator over the key-value pairs of the map.
+    ///
+    /// Each entry is converted from [Val] to `(K, V)` as it is yielded.
+    ///
+    /// ### Panics
+    ///
+    /// If any key or value cannot be converted to its declared type.
+    /// Use [`try_iter`](Map::try_iter) to handle conversion errors.
     #[inline(always)]
     pub fn iter(&self) -> UnwrappedIter<MapTryIter<K, V>, (K, V), ConversionError>
     where
@@ -504,6 +519,8 @@ where
         self.clone().into_iter()
     }
 
+    /// Returns an iterator over the key-value pairs of the map, yielding
+    /// `Result<(K, V), ConversionError>` for each entry.
     #[inline(always)]
     pub fn try_iter(&self) -> MapTryIter<K, V>
     where

soroban-sdk/src/vec.rs

@@ -961,6 +961,14 @@ impl<T> Vec<T>
 where
     T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
 {
+    /// Returns an iterator over the elements of the vec.
+    ///
+    /// Each element is converted from [Val] to `T` as it is yielded.
+    ///
+    /// ### Panics
+    ///
+    /// If any element cannot be converted to type `T`. Use
+    /// [`try_iter`](Vec::try_iter) to handle conversion errors.
     #[inline(always)]
     pub fn iter(&self) -> UnwrappedIter<VecTryIter<T>, T, T::Error>
     where
@@ -970,6 +978,8 @@ where
         self.try_iter().unwrapped()
     }
 
+    /// Returns an iterator over the elements of the vec, yielding
+    /// `Result<T, ConversionError>` for each element.
     #[inline(always)]
     pub fn try_iter(&self) -> VecTryIter<T>
     where