expand docs on ToXdr and FromXdr traits

Author: leighmcculloch

soroban-sdk/src/xdr.rs

@@ -29,18 +29,68 @@ use crate::{
 // Re-export all the XDR from the environment.
 pub use crate::env::xdr::*;
 
-/// Implemented by types that can be serialized to [Bytes].
+/// Implemented by types that can be serialized to [Bytes] as XDR.
 ///
-/// All types that are convertible to [Val] are implemented.
+/// All types that are convertible to [Val] implement this trait. The value is
+/// first converted to a [Val], then serialized to XDR in its [ScVal] form.
+///
+/// ### Examples
+///
+/// ```
+/// use soroban_sdk::{xdr::ToXdr, Env};
+///
+/// let env = Env::default();
+///
+/// let value: u32 = 5;
+/// let bytes = value.to_xdr(&env);
+/// assert_eq!(bytes.len(), 8);
+/// ```
 pub trait ToXdr {
+    /// Serializes the value to XDR as [Bytes].
     fn to_xdr(self, env: &Env) -> Bytes;
 }
 
-/// Implemented by types that can be deserialized from [Bytes].
+/// Implemented by types that can be deserialized from [Bytes] containing XDR.
+///
+/// All types that are convertible from [Val] implement this trait. The bytes
+/// are deserialized from their [ScVal] XDR form into a [Val], then converted
+/// to the target type.
+///
+/// ### Errors
+///
+/// Returns an error if the [Val] cannot be converted into the target type.
+///
+/// ### Panics
+///
+/// Panics if the provided bytes are not valid XDR for an [ScVal].
+///
+/// ### Examples
+///
+/// ```
+/// use soroban_sdk::{xdr::{ToXdr, FromXdr}, Env};
+///
+/// let env = Env::default();
+///
+/// let value: u32 = 5;
+/// let bytes = value.to_xdr(&env);
 ///
-/// All types that are convertible from [Val] are implemented.
+/// let roundtrip = u32::from_xdr(&env, &bytes);
+/// assert_eq!(roundtrip, Ok(5));
+/// ```
 pub trait FromXdr: Sized {
+    /// The error type returned if the [Val] cannot be converted into the
+    /// target type.
     type Error;
+    /// Deserializes the value from XDR [Bytes].
+    ///
+    /// ### Errors
+    ///
+    /// Returns an error if the [Val] cannot be converted into the target
+    /// type.
+    ///
+    /// ### Panics
+    ///
+    /// Panics if the provided bytes are not valid XDR for an [ScVal].
     fn from_xdr(env: &Env, b: &Bytes) -> Result<Self, Self::Error>;
 }