Adding crate-level documentation (#9)

src/serialization.rs

@@ -18,11 +18,80 @@ use crate::{
 use alloc::vec::Vec;
 use generic_array::{typenum::Unsigned, GenericArray};
 
+/// Inner macro used for deriving `serde`'s `Serialize` and `Deserialize` traits.
+macro_rules! impl_serialize_and_deserialize_for {
+    ($t:ident) => {
+        #[cfg(feature = "serialize")]
+        impl<CS: CipherSuite> serde::Serialize for $t<CS> {
+            fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+            where
+                S: serde::Serializer,
+            {
+                if serializer.is_human_readable() {
+                    serializer.serialize_str(&base64::encode(&self.serialize()))
+                } else {
+                    serializer.serialize_bytes(&self.serialize())
+                }
+            }
+        }
+
+        #[cfg(feature = "serialize")]
+        impl<'de, CS: CipherSuite> serde::Deserialize<'de> for $t<CS> {
+            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+            where
+                D: serde::Deserializer<'de>,
+            {
+                if deserializer.is_human_readable() {
+                    let s = <&str>::deserialize(deserializer)?;
+                    $t::<CS>::deserialize(&base64::decode(s).map_err(serde::de::Error::custom)?)
+                        .map_err(serde::de::Error::custom)
+                } else {
+                    struct ByteVisitor<CS: CipherSuite> {
+                        marker: core::marker::PhantomData<CS>,
+                    }
+                    impl<'de, CS: CipherSuite> serde::de::Visitor<'de> for ByteVisitor<CS> {
+                        type Value = $t<CS>;
+                        fn expecting(
+                            &self,
+                            formatter: &mut core::fmt::Formatter,
+                        ) -> core::fmt::Result {
+                            formatter.write_str(core::concat!(
+                                "the byte representation of a ",
+                                core::stringify!($t)
+                            ))
+                        }
+
+                        fn visit_bytes<E>(self, value: &[u8]) -> Result<Self::Value, E>
+                        where
+                            E: serde::de::Error,
+                        {
+                            $t::<CS>::deserialize(value).map_err(|_| {
+                                serde::de::Error::invalid_value(
+                                    serde::de::Unexpected::Bytes(value),
+                                    &core::concat!(
+                                        "invalid byte sequence for ",
+                                        core::stringify!($t)
+                                    ),
+                                )
+                            })
+                        }
+                    }
+                    deserializer.deserialize_bytes(ByteVisitor::<CS> {
+                        marker: core::marker::PhantomData,
+                    })
+                }
+            }
+        }
+    };
+}
+
 //////////////////////////////////////////////////////////
 // Serialization and Deserialization for High-Level API //
 // ==================================================== //
 //////////////////////////////////////////////////////////
 
+impl_serialize_and_deserialize_for!(NonVerifiableClient);
+
 impl<CS: CipherSuite> NonVerifiableClient<CS> {
     /// Serialization into bytes
     pub fn serialize(&self) -> Vec<u8> {
@@ -47,6 +116,8 @@ impl<CS: CipherSuite> NonVerifiableClient<CS> {
     }
 }
 
+impl_serialize_and_deserialize_for!(VerifiableClient);
+
 impl<CS: CipherSuite> VerifiableClient<CS> {
     /// Serialization into bytes
     pub fn serialize(&self) -> Vec<u8> {
@@ -80,6 +151,8 @@ impl<CS: CipherSuite> VerifiableClient<CS> {
     }
 }
 
+impl_serialize_and_deserialize_for!(NonVerifiableServer);
+
 impl<CS: CipherSuite> NonVerifiableServer<CS> {
     /// Serialization into bytes
     pub fn serialize(&self) -> Vec<u8> {
@@ -99,6 +172,8 @@ impl<CS: CipherSuite> NonVerifiableServer<CS> {
     }
 }
 
+impl_serialize_and_deserialize_for!(VerifiableServer);
+
 impl<CS: CipherSuite> VerifiableServer<CS> {
     /// Serialization into bytes
     pub fn serialize(&self) -> Vec<u8> {
@@ -124,6 +199,8 @@ impl<CS: CipherSuite> VerifiableServer<CS> {
     }
 }
 
+impl_serialize_and_deserialize_for!(Proof);
+
 impl<CS: CipherSuite> Proof<CS> {
     /// Serialization into bytes
     pub fn serialize(&self) -> Vec<u8> {
@@ -147,6 +224,8 @@ impl<CS: CipherSuite> Proof<CS> {
     }
 }
 
+impl_serialize_and_deserialize_for!(BlindedElement);
+
 impl<CS: CipherSuite> BlindedElement<CS> {
     /// Serialization into bytes
     pub fn serialize(&self) -> Vec<u8> {
@@ -161,6 +240,8 @@ impl<CS: CipherSuite> BlindedElement<CS> {
     }
 }
 
+impl_serialize_and_deserialize_for!(EvaluationElement);
+
 impl<CS: CipherSuite> EvaluationElement<CS> {
     /// Serialization into bytes
     pub fn serialize(&self) -> Vec<u8> {