From 06ddf00fb4df3290bd3d10034e60cf0df289dc97 Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Fri, 3 Dec 2021 17:37:50 -0700
Subject: [PATCH] elliptic-curve: serde documentation

Document serde serializations provided by this crate
---
 elliptic-curve/Cargo.lock            |  2 +-
 elliptic-curve/src/point.rs          | 11 ++++++++---
 elliptic-curve/src/public_key.rs     | 10 ++++++++++
 elliptic-curve/src/scalar/core.rs    |  8 ++++++++
 elliptic-curve/src/scalar/nonzero.rs |  2 +-
 5 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/elliptic-curve/Cargo.lock b/elliptic-curve/Cargo.lock
index 9755dde9e..8df140834 100644
--- a/elliptic-curve/Cargo.lock
+++ b/elliptic-curve/Cargo.lock
@@ -56,7 +56,7 @@ dependencies = [
 
 [[package]]
 name = "elliptic-curve"
-version = "0.11.2"
+version = "0.11.3"
 dependencies = [
  "base64ct",
  "crypto-bigint",
diff --git a/elliptic-curve/src/point.rs b/elliptic-curve/src/point.rs
index 825db3fd1..7257be66c 100644
--- a/elliptic-curve/src/point.rs
+++ b/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>;
diff --git a/elliptic-curve/src/public_key.rs b/elliptic-curve/src/public_key.rs
index 8875ec987..edc6e6aa6 100644
--- a/elliptic-curve/src/public_key.rs
+++ b/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>
diff --git a/elliptic-curve/src/scalar/core.rs b/elliptic-curve/src/scalar/core.rs
index 5d0bf9e92..40d36083d 100644
--- a/elliptic-curve/src/scalar/core.rs
+++ b/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")))]
diff --git a/elliptic-curve/src/scalar/nonzero.rs b/elliptic-curve/src/scalar/nonzero.rs
index eac39aa9b..3ed35358c 100644
--- a/elliptic-curve/src/scalar/nonzero.rs
+++ b/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()))
     }