From f488a8f80342f1ff730ee7c02c84a319ed789992 Mon Sep 17 00:00:00 2001
From: guorong009 <dgr009@pse.dev>
Date: Wed, 18 Dec 2024 01:13:58 +0800
Subject: [PATCH] chore: add more comments (#387)

* doc: add comments for verifier challenge scalars

* doc: add comments to more structs in "halo2_backend"

* chore: fmt
---
 halo2_backend/src/plonk.rs         | 15 +++++++++++++++
 halo2_backend/src/plonk/circuit.rs |  3 +++
 halo2_backend/src/plonk/keygen.rs  |  2 +-
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/halo2_backend/src/plonk.rs b/halo2_backend/src/plonk.rs
index b4039421d..09e998470 100644
--- a/halo2_backend/src/plonk.rs
+++ b/halo2_backend/src/plonk.rs
@@ -382,22 +382,37 @@ impl<C: CurveAffine> VerifyingKey<C> {
     }
 }
 
+/// Verifier challenge value, used to keep lookup columns linearly independent
+///
+/// Ref: https://zcash.github.io/halo2/design/proving-system/circuit-commitments.html
 #[derive(Clone, Copy, Debug)]
 pub(crate) struct Theta;
 pub(crate) type ChallengeTheta<F> = ChallengeScalar<F, Theta>;
 
+/// Verifier challenge value, used to commit permutation polynomials
+///
+/// Ref: https://zcash.github.io/halo2/design/proving-system/permutation.html
 #[derive(Clone, Copy, Debug)]
 pub(crate) struct Beta;
 pub(crate) type ChallengeBeta<F> = ChallengeScalar<F, Beta>;
 
+/// Verifier challenge value, used to commit permutation polynomials
+///
+/// Ref: https://zcash.github.io/halo2/design/proving-system/permutation.html
 #[derive(Clone, Copy, Debug)]
 pub(crate) struct Gamma;
 pub(crate) type ChallengeGamma<F> = ChallengeScalar<F, Gamma>;
 
+/// Verifier challenge value, used to build quotient polynomial
+///
+/// Ref: https://zcash.github.io/halo2/design/proving-system/vanishing.html
 #[derive(Clone, Copy, Debug)]
 pub(crate) struct Y;
 pub(crate) type ChallengeY<F> = ChallengeScalar<F, Y>;
 
+/// Verifier challenge value, used for multipoint opening argument
+///
+/// Ref: https://zcash.github.io/halo2/design/proving-system/multipoint-opening.html
 #[derive(Clone, Copy, Debug)]
 pub(crate) struct X;
 pub(crate) type ChallengeX<F> = ChallengeScalar<F, X>;
diff --git a/halo2_backend/src/plonk/circuit.rs b/halo2_backend/src/plonk/circuit.rs
index de9c6973f..d3208a9dd 100644
--- a/halo2_backend/src/plonk/circuit.rs
+++ b/halo2_backend/src/plonk/circuit.rs
@@ -4,6 +4,7 @@ use halo2_middleware::expression::{Expression, Variable};
 use halo2_middleware::poly::Rotation;
 use halo2_middleware::{lookup, permutation::ArgumentMid, shuffle};
 
+/// Represent the index, column and rotation of a query, for backwards compatibility
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub struct QueryBack {
     /// Query index
@@ -14,6 +15,7 @@ pub struct QueryBack {
     pub(crate) rotation: Rotation,
 }
 
+/// Represent the `Query` and `Challenge`, for backwards compatibility
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum VarBack {
     /// This is a generic column query
@@ -230,6 +232,7 @@ impl<F: Field> ConstraintSystemBack<F> {
     }
 }
 
+/// A minimum version of `Gates`, which contains the constraint polynomial identities used in circuit.
 struct PinnedGates<'a, F: Field>(&'a Vec<GateBack<F>>);
 
 impl<'a, F: Field> std::fmt::Debug for PinnedGates<'a, F> {
diff --git a/halo2_backend/src/plonk/keygen.rs b/halo2_backend/src/plonk/keygen.rs
index 028812dd1..c9869dbbe 100644
--- a/halo2_backend/src/plonk/keygen.rs
+++ b/halo2_backend/src/plonk/keygen.rs
@@ -179,7 +179,7 @@ where
         ev,
     })
 }
-
+/// A map of whole queries used in the circuit
 struct QueriesMap {
     map: HashMap<(ColumnMid, Rotation), usize>,
     advice: Vec<(ColumnMid, Rotation)>,