Add more documentation for serializing

Author: alexander-zw

ec/src/models/short_weierstrass/mod.rs

@@ -105,6 +105,9 @@ pub trait SWCurveConfig: super::CurveConfig {
         res
     }
 
+    /// If uncompressed, serializes both x and y coordinates as well as a bit for whether it is
+    /// infinity. If compressed, serializes x coordinate with two bits to encode whether y is
+    /// positive, negative, or infinity.
     #[inline]
     fn serialize_with_mode<W: Write>(
         item: &Affine<Self>,
@@ -129,6 +132,7 @@ pub trait SWCurveConfig: super::CurveConfig {
         }
     }
 
+    /// If `validate` is `Yes`, calls `check()` to make sure the element is valid.
     fn deserialize_with_mode<R: Read>(
         mut reader: R,
         compress: Compress,

ec/src/models/twisted_edwards/mod.rs

@@ -85,6 +85,8 @@ pub trait TECurveConfig: super::CurveConfig {
         res
     }
 
+    /// If uncompressed, serializes both x and y coordinates.
+    /// If compressed, serializes y coordinate with a bit to encode whether x is positive.
     #[inline]
     fn serialize_with_mode<W: Write>(
         item: &Affine<Self>,
@@ -101,6 +103,9 @@ pub trait TECurveConfig: super::CurveConfig {
         }
     }
 
+    /// If `validate` is `Yes`, calls `check()` to make sure the element is valid.
+    /// 
+    /// Uses `Affine::get_xs_from_y_unchecked()` for the compressed version.
     fn deserialize_with_mode<R: Read>(
         mut reader: R,
         compress: Compress,

serialize/src/lib.rs

@@ -23,12 +23,16 @@ pub use ark_serialize_derive::*;
 
 use digest::{generic_array::GenericArray, Digest, OutputSizeUser};
 
+/// Whether to use a compressed version of the serialization algorithm. Specific behavior depends
+/// on implementation. If no compressed version exists (e.g. on `Fp`), mode is ignored.
 #[derive(Copy, Clone, PartialEq, Eq)]
 pub enum Compress {
     Yes,
     No,
 }
 
+/// Whether to validate the element after deserializing it. Specific behavior depends on
+/// implementation. If no validation algorithm exists (e.g. on `Fp`), mode is ignored.
 #[derive(Copy, Clone, PartialEq, Eq)]
 pub enum Validate {
     Yes,
@@ -76,6 +80,7 @@ pub trait Valid: Sized + Sync {
 /// }
 /// ```
 pub trait CanonicalSerialize {
+    /// The general serialize method that takes in customization flags.
     fn serialize_with_mode<W: Write>(
         &self,
         writer: W,
@@ -118,6 +123,7 @@ pub trait CanonicalSerialize {
 /// }
 /// ```
 pub trait CanonicalDeserialize: Valid {
+    /// The general deserialize method that takes in customization flags.
     fn deserialize_with_mode<R: Read>(
         reader: R,
         compress: Compress,