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

@@ -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>;

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> {

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)>,