chore(docs): More acir docs

acvm-repo/acir/src/circuit/brillig.rs

@@ -1,3 +1,31 @@
+//! This module contains [Brillig][brillig] structures for integration within an ACIR circuit.
+//!
+//! [Brillig][brillig] is used in ACIR as a hint for the solver when executing the circuit.
+//! Executing Brillig does not generate any constraints and is the result of the compilation of an unconstrained function.
+//!
+//! Let's see an example with euclidean division.
+//! The normal way to compute `a/b`, where `a` and `b` are 8-bits integers, is to
+//! implement the Euclidean algorithm which computes in a loop (or recursively)
+//! modulus of the kind 'a mod b'. Doing this computation requires a lot of steps to
+//! be properly implemented in ACIR, especially the loop with a condition. However,
+//! euclidean division can be easily constrained with one assert-zero opcode:
+//! `a = bq+r`, assuming `q` is 8 bits and `r<b`. Since these assumptions can easily
+//! written with a few range opcodes, euclidean division can in fact be implemented
+//! with a small number of opcodes.
+//!
+//! However, in order to write these opcodes we need the result of the division
+//! which are the witness `q` and `r`. But from the constraint `a=bq+r`, how can the
+//! solver figure out how to solve `q` and `r` with only one equation? This is where
+//! brillig/unconstrained function come into action. We simply define a function that
+//! performs the usual Euclid algorithm to compute `q` and `r` from `a` and `b`.
+//! Since executing Brillig does not generate constraints, it won't be provided to the
+//! proving system but simply used by the solver to compute the values of `q` and
+//! `r`.
+//!
+//! In summary, executing Brillig will perform the computation defined by its
+//! bytecode, on the provided inputs, and assign the result to the outputs witnesses,
+//! without adding any constraints.
+
 use super::opcodes::BlockId;
 use crate::native_types::{Expression, Witness};
 use brillig::Opcode as BrilligOpcode;
@@ -32,6 +60,7 @@ pub struct BrilligBytecode<F> {
 }
 
 /// Id for the function being called.
+/// Indexes into the table of Brillig function's specified in a [program][super::Program]
 #[derive(
     Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Hash, Copy, Default, PartialOrd, Ord,
 )]