Adding doc comments to risc0_zkp crate, mostly in core.

risc0/zkp/rust/src/core/README.md

@@ -1,11 +1,11 @@
 # risc0_zkp::core
 
-This module contains the core objects that are used by the ZK-STARK prover and verifier.
+This module contains the core objects that are used by the zk-STARK prover and verifier.
 
 This includes support for:
-* [fp]: the base finite field
-* [fp4]: the extension finite field
-* [ntt]: Number Theoretic Transform
-* [sha]: SHA256 hashing support
-* [sha_rng]: Cryptographic Random Number Generator (CRNG) based on SHA
-* other basic ZKP utilities
+* [fp]: The base finite field
+* [fp4]: The finite field extension
+* [ntt]: Number-theoretic transform (NTT)
+* [sha]: SHA-256 hashing support
+* [sha_rng]: Cryptographic random number generator (CRNG) based on SHA-256
+* Other basic ZKP utilities

risc0/zkp/rust/src/core/mod.rs

@@ -13,25 +13,31 @@
 // limitations under the License.
 
 #![deny(missing_docs)]
+//! Core objects used by the zk-STARK prover
+//! and verifier.
 #![doc = include_str!("README.md")]
 
 extern crate alloc;
 
 use rand::Rng;
 
-/// Transitional "fp" module until ZKP has been genericized to work
-/// with multiple fields.
+/// This transitional "fp4" module will remain until ZKP has been genericized to
+/// work with multiple fields. This module includes the base field of order
+/// 15*2^27 + 1).
+///
+/// # Example
 pub mod fp {
     pub use crate::field::baby_bear::Elem as Fp;
 }
-/// Transitional "fp4" module until ZKP has been genericized to work
-/// with multiple fields.
+/// This transitional "fp4" module will remain until ZKP has been genericized to
+/// work with multiple fields. This module includes the field extension whose
+/// base field is of order 15*2^27 + 1.
 pub mod fp4 {
     pub use crate::field::baby_bear::ExtElem as Fp4;
     use crate::field::ExtElem;
 
-    /// Transitional reexport until ZKP has been genericized to work
-    /// with multiple fields.
+    /// This transitional re-export will remain until ZKP has been genericized
+    /// to work with multiple fields.
     pub const EXT_SIZE: usize = Fp4::EXT_SIZE;
 }
 pub mod ntt;
@@ -42,13 +48,28 @@ pub mod sha_cpu;
 pub mod sha_rng;
 
 /// For x = (1 << po2), given x, find po2.
+/// # Example
+/// ```
+/// # use risc0_zkp::core::to_po2;
+/// #
+/// assert_eq!(to_po2(7), 2);
+/// assert_eq!(to_po2(10), 3);
+/// ```
 pub fn to_po2(x: usize) -> usize {
     (31 - (x as u32).leading_zeros()) as usize
 }
 
 /// Compute `ceil(log_2(value))`
 ///
-/// Find the smallest value `result` such that `2^result >= value`.
+/// Find the smallest `result` such that, for the provided value,
+/// `2^result >= value`.
+/// # Example
+/// ```
+/// # use risc0_zkp::core::log2_ceil;
+/// #
+/// assert_eq!(log2_ceil(8), 3); // 2^3 = 8
+/// assert_eq!(log2_ceil(32), 5); // 2^5 = 32
+/// ```
 #[inline]
 pub const fn log2_ceil(value: usize) -> usize {
     let mut result = 0;
@@ -65,6 +86,7 @@ pub trait Random {
 }
 
 impl Random for u32 {
+    /// Return a random u32 value.
     fn random<R: Rng>(rng: &mut R) -> Self {
         rng.next_u32()
     }

risc0/zkp/rust/src/core/ntt.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! An implementation of a Numeric Theoretic Transform (NTT).
+//! An implementation of a number-theoretic transform (NTT).
 
 use core::ops::{Add, Mul, Sub};
 
@@ -26,20 +26,46 @@ use super::{
 
 use crate::field::Elem;
 
-/// Reverses the bits in a 32 bit number
-/// For example 1011...0100 becomes 0010...1101
+/// Reverses the bits in a 32-bit number.
+/// # Example
+/// ```
+/// # use risc0_zkp::core::ntt::bit_rev_32;
+/// #
+/// let a: u32 = 2^8 + 2^4 + 1;
+///
+/// assert_eq!(format!("{:b}", a), "1101");
+/// assert_eq!(format!("{:b}", bit_rev_32(a)), "10110000000000000000000000000000");
+/// ```
 pub fn bit_rev_32(mut x: u32) -> u32 {
+    // The values used here are, in binary:
+    // 10101010101010101010101010101010, 01010101010101010101010101010101
     x = ((x & 0xaaaaaaaa) >> 1) | ((x & 0x55555555) << 1);
+    // 110011001100110011001100, 001100110011001100110011
     x = ((x & 0xcccccccc) >> 2) | ((x & 0x33333333) << 2);
+    // 111100001111000011110000, 000011110000111100001111
     x = ((x & 0xf0f0f0f0) >> 4) | ((x & 0x0f0f0f0f) << 4);
+    // 11111111000000001111111100000000, 00000000111111110000000011111111
     x = ((x & 0xff00ff00) >> 8) | ((x & 0x00ff00ff) << 8);
     (x >> 16) | (x << 16)
 }
 
-/// Bit reverses the indices in an array of (1 << n) numbers.
+/// Bit-reverses the indices in an array of (1 << n) numbers.
 /// This permutes the values in the array so that a value which is previously
-/// in index i, will now go in the index i' given by reversing the bits of i.
-/// For example, with n=4, the value at index 3=0011 will go to index 12=1100.
+/// in index i will now go in the index i', given by reversing the bits of i.
+///
+/// # Example
+/// For example, with the array given below of size n=4,
+/// the indices are `0, 1, 2, 3`; bitwise, they're `0, 01, 10, 11`.
+///
+/// Reversed, these give `0, 10, 01, 11`, permuting the second and third
+/// values.
+/// ```
+/// # use risc0_zkp::core::ntt::bit_reverse;
+/// #
+/// let mut some_values = [1, 2, 3, 4];
+/// bit_reverse(&mut some_values);
+/// assert_eq!(some_values, [1, 3, 2, 4]);
+/// ```
 pub fn bit_reverse<T: Copy>(io: &mut [T]) {
     let n = log2_ceil(io.len());
     assert_eq!(1 << n, io.len());
@@ -138,10 +164,10 @@ butterfly!(1, 0);
 
 /// Perform a reverse butterfly transform of a buffer of (1 << n) numbers.
 /// The result of this computation is a discrete Fourier transform, but with
-/// changed indices. This is described [here](https://en.wikipedia.org/wiki/Cooley%E2%80%93Tukey_FFT_algorithm#Data_reordering,_bit_reversal,_and_in-place_algorithms)
-/// The output of rev_butterfly(io, n) at index i is the sum over k from 0 to
-/// 2^n-1 of io\[k\] ROU_REV\[n\]^(k i'), where i' is i bit-reversed as an n-bit
-/// number.
+/// changed indices. This is described [here](https://en.wikipedia.org/wiki/Cooley%E2%80%93Tukey_FFT_algorithm#Data_reordering,_bit_reversal,_and_in-place_algorithms).
+/// The output of `rev_butterfly(io, n)` at index i is the sum over k from 0 to
+/// 2^n-1 of io\[k\] ROU_REV\[n\]^(k i'), where i' is i bit-reversed as an
+/// n-bit number and ROU_REV are the 'reverse' roots of unity.
 ///
 /// As an example, we'll work through a trace of the rev_butterfly algorithm
 /// with n = 3 on a list of length 8. Let w = ROU_REV\[3\] be the eighth root of
@@ -346,7 +372,7 @@ mod tests {
         let mut buf = [Fp::random(&mut rng); SIZE];
         // Copy it
         let orig = buf.clone();
-        // Now go backwords
+        // Now go backwards
         interpolate_ntt(&mut buf);
         // Make sure something changed
         assert_ne!(orig, buf);

risc0/zkp/rust/src/core/poly.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Polynomial utilites (currently only evaluation).
+//! Polynomial utilities (currently only those used in polynomial evaluation).
 
 use alloc::vec;
 

risc0/zkp/rust/src/core/rou.rs

@@ -12,15 +12,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Tables containing the root of unity for the base field.
-//!
-//! There are two table, which are inverses of each other.
+//! Tables containing the roots of unity (currently for the base
+//! field of order `15*2^27 + 1`).
+//! There are two tables, each of which are inverses of the other.
 
-/// Maximum root of unity which is a power of 2, i.e. there is 2^27th root of
-/// unity, but no 2^28th.
+/// Maximum root of unity which is a power of 2. For example, for the base field
+/// of order `15*2^27 + 1`, there is a 2^27th root of unity , but not a 2^28th.
 pub const MAX_ROU_PO2: usize = 27;
 
-/// For each power of 2, what is the 'forward' root of unity for the po2.
+/// For each power of 2, the 'forward' root of unity for the po2.
 /// That is, this list satisfies ROU_FWD\[i+1\] ^ 2 = ROU_FWD\[i\] in the prime
 /// field F_2013265921, which implies ROU_FWD\[i\] ^ (2 ^ i) = 1.
 pub const ROU_FWD: [u32; MAX_ROU_PO2 + 1] = [
@@ -30,7 +30,7 @@ pub const ROU_FWD: [u32; MAX_ROU_PO2 + 1] = [
     352275361, 18769, 137,
 ];
 
-/// For each power of 2, what is the 'reverse' root of unity for the po2.
+/// For each power of 2, the 'reverse' root of unity for the po2.
 /// This list satisfies ROU_FWD\[i\] * ROU_REV\[i\] = 1 in the prime field
 /// F_2013265921.
 pub const ROU_REV: [u32; MAX_ROU_PO2 + 1] = [

risc0/zkp/rust/src/core/sha_cpu.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Simple SHA-256 wrappers.
+//! Simple wrappers for a CPU-based SHA-256 implementation.
 
 use alloc::{boxed::Box, vec, vec::Vec};
 use core::slice;

risc0/zkp/rust/src/core/sha_rng.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! A SHA-256 based CRNG used in Fiat-Shamir
+//! A SHA-256 based CRNG used in Fiat-Shamir.
 use rand::{Error, RngCore};
 use rand_core::impls;
 

risc0/zkp/rust/src/field/mod.rs

@@ -13,7 +13,8 @@
 // limitations under the License.
 
 // TODO: Document better
-
+//! Defines field extension (and base fields) used for finite field-based
+//! operations across the RISC Zero zkVM architecture
 use core::{cmp, ops};
 
 /// Subfield elements that can be compared, copied, and operated
@@ -125,7 +126,8 @@ pub mod test {
     where
         F: Into<u64> + From<u64> + Debug,
     {
-        // We do 128-bit arithmetic so we don't have to worry about overflows.
+        // For testng, we do 128-bit arithmetic so we don't have to worry about
+        // overflows.
         let p: u128 = p_u64 as _;
 
         assert_eq!(F::from(0), F::ZERO);
@@ -136,8 +138,8 @@ pub mod test {
         assert_eq!(F::ZERO.inv(), F::ZERO);
         assert_eq!(F::ONE.inv(), F::ONE);
 
-        // Compare against a bunch of numbers to make sure it matches
-        // with regular modulo arithmetic.
+        // Compare against many randomly generated numbers to make sure results match
+        // the expected results for regular modular arithmetic.
         let mut rng = rand::thread_rng();
 
         for _ in 0..1000 {

risc0/zkp/rust/src/hal/cpu.rs

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Hardware abstraction layer for RISC Zero zkVM
 use core::{
     cell::{Ref, RefMut},
     ops::Range,

risc0/zkp/rust/src/hal/mod.rs

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Hardware abstraction layer for RISC Zero zkVM
 pub mod cpu;
 
 use crate::core::{fp::Fp, fp4::Fp4, sha::Digest};