Document ToXdr and FromXdr traits (#1767)

### What
Added documentation to the `ToXdr` and `FromXdr` traits explaining the
two-step serialization process: values are first converted to a `Val`,
then serialized to XDR in their `ScVal` form. Added `Errors` and
`Panics` sections to `FromXdr` and `from_xdr`, doc examples on both
traits, and doc comments on the `to_xdr`, `from_xdr` methods and the
`Error` associated type.

### Why
`FromXdr::from_xdr` panics if the provided bytes are not valid XDR for
an `ScVal`, but returns an error if the `Val` cannot be converted into
the target type. This distinction was undocumented. The panic originates
from the host side, making it non-obvious even when reading the
implementation.

Close #1766

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>;
 }