Add some more + module doc

plonky2/src/fri/mod.rs

@@ -1,3 +1,6 @@
+//! Fast Reed-Solomon IOP (FRI) protocol and its circuit version
+//! of the FRI verifier for recursive proof composition.
+
 use alloc::vec::Vec;
 
 use serde::Serialize;

plonky2/src/gadgets/mod.rs

@@ -1,4 +1,5 @@
-//! Gadgets provide additional methods to [`CircuitBuilder`]
+//! Helper gadgets providing additional methods to
+//! [CircuitBuilder](crate::plonk::circuit_builder::CircuitBuilder),
 //! to ease circuit creation.
 
 pub mod arithmetic;

plonky2/src/gates/mod.rs

@@ -1,3 +1,25 @@
+//! plonky2 custom gates.
+//!
+//! Vanilla Plonk arithmetization only supports basic fan-in 2 / fan-out 1 arithmetic gates,
+//! each of the form
+//!
+//! $$ a.b.q_M + a.q_L + b.q_R + c.q_O + q_C = 0 $$
+//!
+//! where:
+//! - q_M, q_L, q_R and q_O are boolean selectors,
+//! - a, b and c are values used as inputs and output respectively,
+//! - q_C is a constant (possibly 0).
+//!
+//! This allows expressing simple operations like multiplication, addition, etc. For
+//! instance, to define a multiplication, one can set q_M=1, q_L=q_R=0, q_O = -1 and q_C = 0.
+//! Hence, the gate equation simplifies to a.b - c = 0, or a.b = c.
+//!
+//! However, such gate is fairly limited for more complex computations. Hence, when a computation may
+//! require too many of these "vanilla" gates, or when a computation arises often within the same circuit,
+//! one may want to construct a tailored custom gate. These custom gates can use more selectors and are
+//! not necessarily limited to 2 inputs + 1 output = 3 wires.
+//! For instance, plonky2 supports natively a custom Poseidon hash gate that uses 135 wires.
+
 // Gates have `new` methods that return `GateRef`s.
 
 pub mod arithmetic_base;

plonky2/src/hash/mod.rs

@@ -1,3 +1,6 @@
+//! plonky2 hashing logic for in-circuit hashing and Merkle proof verification
+//! as well as specific hash functions implementation.
+
 mod arch;
 pub mod hash_types;
 pub mod hashing;

plonky2/src/lib.rs

@@ -4,6 +4,7 @@
 
 pub extern crate alloc;
 
+/// Re-export of `plonky2_field`.
 #[doc(inline)]
 pub use plonky2_field as field;
 

plonky2/src/plonk/circuit_builder.rs

@@ -136,7 +136,7 @@ pub struct LookupWire {
 /// assert!(circuit_data.verify(proof).is_ok());
 /// ```
 pub struct CircuitBuilder<F: RichField + Extendable<D>, const D: usize> {
-    /// Circuit configuration to be used by this `CircuitBuilder`.
+    /// Circuit configuration to be used by this [`CircuitBuilder`].
     pub config: CircuitConfig,
 
     /// A domain separator, which is included in the initial Fiat-Shamir seed. This is generally not
@@ -179,7 +179,7 @@ pub struct CircuitBuilder<F: RichField + Extendable<D>, const D: usize> {
     /// List of constant generators used to fill the constant wires.
     constant_generators: Vec<ConstantGenerator<F>>,
 
-    /// Rows for each LUT: LookupWire contains: first `LookupGate`, first `LookupTableGate`, last `LookupTableGate`.
+    /// Rows for each LUT: LookupWire contains: first `LookupGate`, first [`LookupTableGate`], last `LookupTableGate`.
     lookup_rows: Vec<LookupWire>,
 
     /// For each LUT index, vector of `(looking_in, looking_out)` pairs.

plonky2/src/plonk/mod.rs

@@ -1,3 +1,8 @@
+//! plonky2 proving system.
+//!
+//! This module also defines the [CircuitBuilder](circuit_builder::CircuitBuilder)
+//! structure, used to build custom plonky2 circuits satisfying arbitrary statements.
+
 pub mod circuit_builder;
 pub mod circuit_data;
 pub mod config;

plonky2/src/recursion/mod.rs

@@ -1,3 +1,9 @@
+//! Recursion logic for verifying recursively plonky2 circuits.
+//!
+//! This module also provides ways to perform conditional recursive verification
+//! (between two different circuits, depending on a condition), and cyclic
+//! recursion where a circuit implements its own verification logic.
+
 pub mod conditional_recursive_verifier;
 pub mod cyclic_recursion;
 pub mod dummy_circuit;

plonky2/src/util/mod.rs

@@ -1,3 +1,5 @@
+//! Utility module for helper methods and plonky2 serialization logic.
+
 use alloc::vec::Vec;
 
 use plonky2_maybe_rayon::*;

plonky2/src/util/serialization/gate_serialization.rs

@@ -59,7 +59,7 @@ macro_rules! get_gate_tag_impl {
 }
 
 #[macro_export]
-/// Macro implementing the `GateSerializer` trait.
+/// Macro implementing the [`GateSerializer`] trait.
 /// To serialize a list of gates used for a circuit,
 /// this macro should be called with a struct on which to implement
 /// this as first argument, followed by all the targeted gates.

plonky2/src/util/serialization/generator_serialization.rs

@@ -63,7 +63,7 @@ macro_rules! get_generator_tag_impl {
 }
 
 #[macro_export]
-/// Macro implementing the `WitnessGeneratorSerializer` trait.
+/// Macro implementing the [`WitnessGeneratorSerializer`] trait.
 /// To serialize a list of generators used for a circuit,
 /// this macro should be called with a struct on which to implement
 /// this as first argument, followed by all the targeted generators.