elliptic-curve: serde documentation (#831)

Document serde serializations provided by this crate

elliptic-curve/src/point.rs

@@ -9,14 +9,19 @@ pub trait AffineXCoordinate<C: Curve> {
     fn x(&self) -> FieldBytes<C>;
 }
 
-/// Attempt to decompress an elliptic curve point from its x-coordinate and
-/// a boolean flag indicating whether or not the y-coordinate is odd.
+/// Decompress an elliptic curve point.
+///
+/// Point decompression recovers an original curve point from its x-coordinate
+/// and a boolean flag indicating whether or not the y-coordinate is odd.
 pub trait DecompressPoint<C: Curve>: Sized {
     /// Attempt to decompress an elliptic curve point.
     fn decompress(x: &FieldBytes<C>, y_is_odd: Choice) -> CtOption<Self>;
 }
 
-/// Attempt to decompact an elliptic curve point from an x-coordinate.
+/// Decompact an elliptic curve point from an x-coordinate.
+///
+/// Decompaction relies on properties of specially-generated keys but provides
+/// a more compact representation than standard point compression.
 pub trait DecompactPoint<C: Curve>: Sized {
     /// Attempt to decompact an elliptic curve point
     fn decompact(x: &FieldBytes<C>) -> CtOption<Self>;

elliptic-curve/src/public_key.rs

@@ -61,6 +61,16 @@ use serde::{de, ser, Deserialize, Serialize};
 ///
 /// When the `pem` feature of this crate (or a specific RustCrypto elliptic
 /// curve crate) is enabled, a [`FromStr`] impl is also available.
+///
+/// # `serde` support
+///
+/// When the optional `serde` feature of this create is enabled, [`Serialize`]
+/// and [`Deserialize`] impls are provided for this type.
+///
+/// The serialization is binary-oriented and supports ASN.1 DER
+/// Subject Public Key Info (SPKI) as the encoding format.
+///
+/// For a more text-friendly encoding of public keys, use [`JwkEcKey`] instead.
 #[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct PublicKey<C>

elliptic-curve/src/scalar/core.rs

@@ -33,6 +33,14 @@ use serde::{de, ser, Deserialize, Serialize};
 /// This type provides a baseline level of scalar arithmetic functionality
 /// which is always available for all curves, regardless of if they implement
 /// any arithmetic traits.
+///
+/// # `serde` support
+///
+/// When the optional `serde` feature of this create is enabled, [`Serialize`]
+/// and [`Deserialize`] impls are provided for this type.
+///
+/// The serialization is a fixed-width big endian encoding. When used with
+/// textual formats, the binary data is encoded as hexadecimal.
 // TODO(tarcieri): make this a fully generic `Scalar` type and use it for `ScalarArithmetic`
 #[derive(Copy, Clone, Debug, Default)]
 #[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]

elliptic-curve/src/scalar/nonzero.rs

@@ -61,7 +61,7 @@ where
         Scalar::<C>::from_repr(repr).and_then(Self::new)
     }
 
-    /// Create a [`NonZeroScalar`] from a [`UInt`].
+    /// Create a [`NonZeroScalar`] from a `C::UInt`.
     pub fn from_uint(uint: C::UInt) -> CtOption<Self> {
         ScalarCore::new(uint).and_then(|scalar| Self::new(scalar.into()))
     }