Some more

plonky2/src/gadgets/arithmetic.rs

@@ -191,7 +191,7 @@ impl<F: RichField + Extendable<D>, const D: usize> CircuitBuilder<F, D> {
         self.arithmetic(F::ONE, F::ONE, x, one, y)
     }
 
-    /// Add `n` `Target`s.
+    /// Adds `n` `Target`s.
     pub fn add_many<T>(&mut self, terms: impl IntoIterator<Item = T>) -> Target
     where
         T: Borrow<Target>,
@@ -224,7 +224,7 @@ impl<F: RichField + Extendable<D>, const D: usize> CircuitBuilder<F, D> {
             .fold(self.one(), |acc, t| self.mul(acc, *t.borrow()))
     }
 
-    /// Exponentiate `base` to the power of `2^power_log`.
+    /// Exponentiates `base` to the power of `2^power_log`.
     pub fn exp_power_of_2(&mut self, base: Target, power_log: usize) -> Target {
         if power_log > self.num_base_arithmetic_ops_per_gate() {
             // Cheaper to just use `ExponentiateGate`.
@@ -239,7 +239,7 @@ impl<F: RichField + Extendable<D>, const D: usize> CircuitBuilder<F, D> {
     }
 
     // TODO: Test
-    /// Exponentiate `base` to the power of `exponent`, given by its little-endian bits.
+    /// Exponentiates `base` to the power of `exponent`, given by its little-endian bits.
     pub fn exp_from_bits(
         &mut self,
         base: Target,
@@ -264,7 +264,7 @@ impl<F: RichField + Extendable<D>, const D: usize> CircuitBuilder<F, D> {
     }
 
     // TODO: Test
-    /// Exponentiate `base` to the power of `exponent`, where `exponent < 2^num_bits`.
+    /// Exponentiates `base` to the power of `exponent`, where `exponent < 2^num_bits`.
     pub fn exp(&mut self, base: Target, exponent: Target, num_bits: usize) -> Target {
         let exponent_bits = self.split_le(exponent, num_bits);
 
@@ -303,7 +303,7 @@ impl<F: RichField + Extendable<D>, const D: usize> CircuitBuilder<F, D> {
         product
     }
 
-    /// Exponentiate `base` to the power of a known `exponent`.
+    /// Exponentiates `base` to the power of a known `exponent`.
     // TODO: Test
     pub fn exp_u64(&mut self, base: Target, mut exponent: u64) -> Target {
         let mut exp_bits = Vec::new();
@@ -330,28 +330,32 @@ impl<F: RichField + Extendable<D>, const D: usize> CircuitBuilder<F, D> {
         self.inverse_extension(x_ext).0[0]
     }
 
+    /// Computes the logical NOT of the provided [`BoolTarget`].
     pub fn not(&mut self, b: BoolTarget) -> BoolTarget {
         let one = self.one();
         let res = self.sub(one, b.target);
         BoolTarget::new_unsafe(res)
     }
 
+    /// Computes the logical AND of the provided [`BoolTarget`]s.
     pub fn and(&mut self, b1: BoolTarget, b2: BoolTarget) -> BoolTarget {
         BoolTarget::new_unsafe(self.mul(b1.target, b2.target))
     }
 
-    /// computes the arithmetic extension of logical "or": `b1 + b2 - b1 * b2`
+    /// Computes the logical OR through the arithmetic expression: `b1 + b2 - b1 * b2`.
     pub fn or(&mut self, b1: BoolTarget, b2: BoolTarget) -> BoolTarget {
         let res_minus_b2 = self.arithmetic(-F::ONE, F::ONE, b1.target, b2.target, b1.target);
         BoolTarget::new_unsafe(self.add(res_minus_b2, b2.target))
     }
 
+    /// Outputs `x` if `b` is true, and else `y`, through the formula: `b*x + (1-b)*y`.
     pub fn _if(&mut self, b: BoolTarget, x: Target, y: Target) -> Target {
         let not_b = self.not(b);
         let maybe_x = self.mul(b.target, x);
         self.mul_add(not_b.target, y, maybe_x)
     }
 
+    /// Checks whether `x` and `y` are equal and outputs the boolean result.
     pub fn is_equal(&mut self, x: Target, y: Target) -> BoolTarget {
         let zero = self.zero();
 

plonky2/src/plonk/circuit_builder.rs

@@ -1,3 +1,5 @@
+//! Logic for building plonky2 circuits.
+
 use alloc::collections::BTreeMap;
 use alloc::sync::Arc;
 use alloc::vec;

plonky2/src/plonk/circuit_data.rs

@@ -1,3 +1,17 @@
+//! Circuit data specific to the prover and the verifier.
+//!
+//! This module also defines a [`CircuitConfig`] to be customized
+//! when building circuits for arbitrary statements.
+//!
+//! After building a circuit, one obtains an instance of [`CircuitData`].
+//! This contains both prover and verifier data, allowing to generate
+//! proofs for the given circuit and verify them.
+//!
+//! Most of the [`CircuitData`] is actually prover-specific, and can be
+//! extracted by calling [`CircuitData::prover_data`] method.
+//! The verifier data can similarly be extracted by calling [`CircuitData::verifier_data`].
+//! This is useful to allow even small devices to verify plonky2 proofs.
+
 use alloc::collections::BTreeMap;
 use alloc::vec;
 use alloc::vec::Vec;

plonky2/src/plonk/config.rs

@@ -1,3 +1,11 @@
+//! Hashing configuration to be used when building a circuit.
+//!
+//! This module defines a [`Hasher`] trait as well as its recursive
+//! counterpart [`AlgebraicHasher`] for in-circuit hashing. It also
+//! provides concrete configurations, one fully recursive leveraging
+//! Poseidon hash function both internally and natively, and one mixing
+//! Poseidon internally and truncated Keccak externally.
+
 use alloc::vec;
 use alloc::vec::Vec;
 use core::fmt::Debug;

plonky2/src/plonk/plonk_common.rs

@@ -1,3 +1,5 @@
+//! Utility methods and constants for Plonk.
+
 use alloc::vec;
 use alloc::vec::Vec;
 

plonky2/src/plonk/proof.rs

@@ -1,3 +1,9 @@
+//! plonky2 proof definition.
+//!
+//! Proofs can be later compressed to reduce their size, into either
+//! [`CompressedProof`] or [`CompressedProofWithPublicInputs`] formats.
+//! The latter can be directly passed to a verifier to assert its correctness.
+
 use alloc::vec;
 use alloc::vec::Vec;
 

plonky2/src/plonk/prover.rs

@@ -1,3 +1,5 @@
+//! plonky2 prover implementation.
+
 use alloc::vec::Vec;
 use alloc::{format, vec};
 use core::cmp::min;

plonky2/src/plonk/vars.rs

@@ -1,3 +1,5 @@
+//! Logic for evaluating constraints.
+
 use core::ops::Range;
 
 use crate::field::extension::algebra::ExtensionAlgebra;

plonky2/src/plonk/verifier.rs

@@ -1,3 +1,5 @@
+//! plonky2 verifier implementation.
+
 use anyhow::{ensure, Result};
 
 use crate::field::extension::Extendable;