Crate docs

zcash_primitives/src/block.rs

@@ -1,3 +1,5 @@
+//! Structs and methods for handling Zcash block headers.
+
 use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
 use hex;
 use std::fmt;

zcash_primitives/src/block/equihash.rs

@@ -1,3 +1,7 @@
+//! Verification functions for the [Equihash] proof-of-work algorithm.
+//!
+//! [Equihash]: https://zips.z.cash/protocol/protocol.pdf#equihash
+
 use blake2b_simd::{Hash as Blake2bHash, Params as Blake2bParams, State as Blake2bState};
 use byteorder::{BigEndian, LittleEndian, ReadBytesExt, WriteBytesExt};
 use log::error;

zcash_primitives/src/constants.rs

@@ -1,3 +1,5 @@
+//! Various constants used by the Zcash primitives.
+
 /// First 64 bytes of the BLAKE2s input during group hash.
 /// This is chosen to be some random string that we couldn't have anticipated when we designed
 /// the algorithm, for rigidity purposes.

zcash_primitives/src/group_hash.rs

@@ -1,3 +1,7 @@
+//! Implementation of [group hashing into Jubjub][grouphash].
+//!
+//! [grouphash]: https://zips.z.cash/protocol/protocol.pdf#concretegrouphashjubjub
+
 use crate::jubjub::{edwards, JubjubEngine, PrimeOrder};
 
 use ff::PrimeField;

zcash_primitives/src/jubjub/mod.rs

@@ -1,3 +1,6 @@
+//! The [Jubjub] curve for efficient elliptic curve operations in circuits built
+//! over [BLS12-381].
+//!
 //! Jubjub is a twisted Edwards curve defined over the BLS12-381 scalar
 //! field, Fr. It takes the form `-x^2 + y^2 = 1 + dx^2y^2` with
 //! `d = -(10240/10241)`. It is birationally equivalent to a Montgomery
@@ -16,6 +19,9 @@
 //! It is a complete twisted Edwards curve, so the equivalence with
 //! the Montgomery curve forms a group isomorphism, allowing points
 //! to be freely converted between the two forms.
+//!
+//! [Jubjub]: https://zips.z.cash/protocol/protocol.pdf#jubjub
+//! [BLS12-381]: pairing::bls12_381
 
 use ff::{Field, PrimeField, SqrtField};
 use pairing::Engine;

zcash_primitives/src/keys.rs

@@ -1,6 +1,8 @@
 //! Sapling key components.
 //!
-//! Implements section 4.2.2 of the Zcash Protocol Specification.
+//! Implements [section 4.2.2] of the Zcash Protocol Specification.
+//!
+//! [section 4.2.2]: https://zips.z.cash/protocol/protocol.pdf#saplingkeycomponents
 
 use crate::{
     jubjub::{edwards, FixedGenerators, JubjubEngine, JubjubParams, ToUniform, Unknown},

zcash_primitives/src/lib.rs

@@ -1,3 +1,8 @@
+//! *General Zcash primitives.*
+//!
+//! `zcash_primitives` is a library that provides the core structs and functions necessary
+//! for working with Zcash.
+
 // Catch documentation errors caused by code changes.
 #![deny(intra_doc_link_resolution_failure)]
 

zcash_primitives/src/pedersen_hash.rs

@@ -1,3 +1,5 @@
+//! Implementation of the Pedersen hash function used in Sapling.
+
 use crate::jubjub::*;
 use ff::{Field, PrimeField, PrimeFieldRepr};
 

zcash_primitives/src/primitives.rs

@@ -1,3 +1,5 @@
+//! Structs for core Zcash primitives.
+
 use ff::{Field, PrimeField, PrimeFieldRepr};
 
 use crate::constants;

zcash_primitives/src/redjubjub.rs

@@ -1,5 +1,7 @@
-//! Implementation of RedJubjub, a specialization of RedDSA to the Jubjub curve.
-//! See section 5.4.6 of the Sapling protocol specification.
+//! Implementation of [RedJubjub], a specialization of RedDSA to the Jubjub
+//! curve.
+//!
+//! [RedJubjub]: https://zips.z.cash/protocol/protocol.pdf#concretereddsa
 
 use crate::jubjub::{edwards::Point, FixedGenerators, JubjubEngine, JubjubParams, Unknown};
 use ff::{Field, PrimeField, PrimeFieldRepr};

zcash_primitives/src/transaction/components.rs

@@ -1,3 +1,5 @@
+//! Structs representing the components within Zcash transactions.
+
 use crate::jubjub::{edwards, Unknown};
 use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
 use ff::{PrimeField, PrimeFieldRepr};

zcash_primitives/src/transaction/mod.rs

@@ -1,3 +1,5 @@
+//! Structs and methods for handling Zcash transactions.
+
 use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
 use hex;
 use sha2::{Digest, Sha256};

zcash_primitives/src/zip32.rs

@@ -1,3 +1,7 @@
+//! Implementation of [ZIP 32] for hierarchical deterministic key management.
+//!
+//! [ZIP 32]: https://zips.z.cash/zip-0032
+
 use aes::Aes256;
 use blake2b_simd::Params as Blake2bParams;
 use byteorder::{ByteOrder, LittleEndian, ReadBytesExt, WriteBytesExt};