Add more comments and docs

expander_compiler/ec_go_lib/src/compile.rs

@@ -1,3 +1,5 @@
+//! This module provides the FFI API for compilation functions.
+
 use libc::{c_ulong, malloc};
 use std::ptr;
 use std::slice;
@@ -9,6 +11,7 @@ use serdes::ExpSerde;
 
 use super::{match_config_id, ByteArray, Config};
 
+/// This struct represents the result of the compilation process.
 #[repr(C)]
 pub struct CompileResult {
     ir_witness_gen: ByteArray,
@@ -107,6 +110,7 @@ fn to_compile_result(result: Result<(Vec<u8>, Vec<u8>), String>) -> CompileResul
     }
 }
 
+/// This function compiles the IR source code into a layered circuit and a witness generator.
 #[no_mangle]
 pub extern "C" fn compile(ir_source: ByteArray, config_id: c_ulong) -> CompileResult {
     let ir_source = unsafe { slice::from_raw_parts(ir_source.data, ir_source.length as usize) };

expander_compiler/ec_go_lib/src/lib.rs

@@ -1,6 +1,10 @@
+//! This module provides the FFI API for the Expander Compiler, especially for the use of the Go language.
+
 use expander_compiler::circuit::config::Config;
 use libc::{c_uchar, c_ulong};
 
+/// ABI version for the Expander Compiler.
+/// The ABI version is used to ensure compatibility between different versions of the library.
 const ABI_VERSION: c_ulong = 4;
 
 #[macro_export]
@@ -19,12 +23,14 @@ macro_rules! match_config_id {
 pub mod compile;
 pub mod proving;
 
+/// This struct represents a byte array used in the FFI API.
 #[repr(C)]
 pub struct ByteArray {
     data: *mut c_uchar,
     length: c_ulong,
 }
 
+/// This function returns the ABI version for the Expander Compiler.
 #[no_mangle]
 pub extern "C" fn abi_version() -> c_ulong {
     ABI_VERSION

expander_compiler/ec_go_lib/src/proving.rs

@@ -1,3 +1,5 @@
+//! This module provides the FFI API for proving functions.
+
 use std::ptr;
 use std::slice;
 
@@ -65,6 +67,7 @@ fn verify_circuit_file_inner<C: config::Config>(
     Ok(executor::verify::<C>(&mut circuit, mpi_config, &proof, &claimed_v) as u8)
 }
 
+/// This function proves a circuit file with the given witness and configuration ID.
 #[no_mangle]
 pub extern "C" fn prove_circuit_file(
     circuit_filename: ByteArray,
@@ -98,6 +101,7 @@ pub extern "C" fn prove_circuit_file(
     }
 }
 
+/// This function verifies a circuit file with the given witness, proof, and configuration ID.
 #[no_mangle]
 pub extern "C" fn verify_circuit_file(
     circuit_filename: ByteArray,

expander_compiler/macros/src/lib.rs

@@ -1,3 +1,5 @@
+//! This crate provides macros for the Expander Compiler, including `memorized` and `kernel` attributes, and `call_kernel` macro.
+
 use proc_macro::TokenStream;
 use quote::{format_ident, quote};
 use syn::{
@@ -79,6 +81,15 @@ fn analyze_type_structure(ty: &Type, allow_primitive: bool) -> Option<(ParamKind
     None
 }
 
+/// This macro defines a function that can be used to memorize the results of a computation.
+///
+/// It generates a new function with the same signature as the original function, but with an additional layer of caching.
+/// The generated function will hash the input parameters and check if the result is already cached.
+/// If the result is cached, it will return the cached result; otherwise, it will call the original function and cache the result.
+///
+/// The function signature must have at least one argument, which is the API argument.
+///
+/// The name of the generated function will be `memorized_<original_function_name>`.
 #[proc_macro_attribute]
 pub fn memorized(_attr: TokenStream, item: TokenStream) -> TokenStream {
     let input_fn = parse_macro_input!(item as ItemFn);
@@ -490,6 +501,12 @@ fn generate_flatten_code(
     quote! { #loop_code }
 }
 
+/// This macro defines a kernel function that can be used in the Expander Compiler.
+///
+/// It generates a new function to compile the kernel, which will be used to create a `Kernel` object.
+/// The kernel function must have at least one argument, which is the API argument.
+///
+/// The name of the generated function will be `compile_<original_function_name>`.
 #[proc_macro_attribute]
 pub fn kernel(_attr: TokenStream, item: TokenStream) -> TokenStream {
     // eprintln!("Input tokens: {:#?}", item);
@@ -650,6 +667,9 @@ impl Parse for KernelCall {
     }
 }
 
+/// This macro generates code to call a kernel function with the provided context and arguments.
+///
+/// It collects all argument names, handles mutable arguments, and generates the necessary code to call the kernel.
 #[proc_macro]
 pub fn call_kernel(input: TokenStream) -> TokenStream {
     let KernelCall {
@@ -658,10 +678,8 @@ pub fn call_kernel(input: TokenStream) -> TokenStream {
         args,
     } = parse_macro_input!(input as KernelCall);
 
-    // 收集所有参数名
     let arg_names: Vec<_> = args.iter().map(|arg| &arg.name).collect();
 
-    // 分别收集可变参数的名称和索引
     let mut_vars: Vec<_> = args
         .iter()
         .enumerate()
@@ -674,7 +692,6 @@ pub fn call_kernel(input: TokenStream) -> TokenStream {
         quote! { #var_name = io[#idx].clone(); }
     });
 
-    // 生成代码
     let expanded = quote! {
         let mut io = [#(#arg_names),*];
         #ctx.call_kernel(&#kernel_name, &mut io);