From 17c7ef717724a901f6672d1b144de41c4f5d088c Mon Sep 17 00:00:00 2001
From: Jonathan LEI <me@xjonathan.dev>
Date: Wed, 23 Oct 2024 03:12:09 +0800
Subject: [PATCH] docs: better docs for `Encode` and `Decode` (#672)

---
 starknet-core/src/codec.rs | 55 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/starknet-core/src/codec.rs b/starknet-core/src/codec.rs
index b5ab08fb..6d3b8a11 100644
--- a/starknet-core/src/codec.rs
+++ b/starknet-core/src/codec.rs
@@ -20,6 +20,34 @@ pub trait FeltWriter {
 
 /// Any type that can be serialized into a series of [Felt]s. This trait corresponds to the
 /// `serialize` function of the Cairo `Serde` trait.
+///
+/// This trait can be derived as long as all the fields in type implement [`Encode`].
+///
+/// # Example
+///
+/// This example demonstrates deriving the trait and then using it to serialize an instance into
+/// [`Vec<Felt>`].
+///
+/// ```rust
+/// use starknet_core::codec::Encode;
+/// # use starknet_core::types::Felt;
+///
+/// #[derive(Encode)]
+/// # #[starknet(core = "starknet_core")]
+/// struct CairoType {
+///     a: u32,
+///     b: Option<bool>,
+/// }
+///
+/// let instance = CairoType {
+///     a: 3,
+///     b: Some(true),
+/// };
+/// let mut serialized = vec![];
+/// instance.encode(&mut serialized);
+///
+/// assert_eq!(vec![Felt::THREE, Felt::ZERO, Felt::ONE], serialized);
+/// ```
 pub trait Encode {
     /// Converts the type into a list of [`Felt`] and append them into the writer.
     fn encode<W: FeltWriter>(&self, writer: &mut W) -> Result<(), Error>;
@@ -27,6 +55,33 @@ pub trait Encode {
 
 /// Any type that can be deserialized from a series of [Felt]s. This trait corresponds to the
 /// `deserialize` function of the Cairo `Serde` trait.
+///
+/// This trait can be derived as long as all the fields in type implement [`Encode`].
+///
+/// # Example
+///
+/// This example demonstrates deriving the trait and then using it to deserialize an instance from
+/// [`Vec<Felt>`].
+///
+/// ```rust
+/// use starknet_core::codec::Decode;
+/// # use starknet_core::types::Felt;
+///
+/// #[derive(Debug, PartialEq, Eq, Decode)]
+/// # #[starknet(core = "starknet_core")]
+/// struct CairoType {
+///     a: u32,
+///     b: Option<bool>,
+/// }
+///
+/// assert_eq!(
+///     CairoType {
+///         a: 3,
+///         b: Some(true)
+///     },
+///     CairoType::decode(&[Felt::THREE, Felt::ZERO, Felt::ONE]).unwrap()
+/// );
+/// ```
 pub trait Decode<'a>: Sized {
     /// Converts into the type from a list of [`Felt`].
     fn decode<T>(reader: T) -> Result<Self, Error>