docs(zkvms/jolt): Add detailed documentation comments

3 files changed, 41 insertions, 1 deletions

diff --git a/zkvms/jolt/guest/Cargo.toml b/zkvms/jolt/guest/Cargo.toml
index b42616e..b958c9d 100644
--- a/zkvms/jolt/guest/Cargo.toml
+++ b/zkvms/jolt/guest/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "guest"
+description = "Jolt's specific guest crate, which includes the chosen guest in guests"
 version = "0.1.0"
 edition = "2021"
 
@@ -11,3 +12,6 @@ path = "./src/lib.rs"
 jolt = { package = "jolt-sdk", path = "/nix/store/q8ix3vj7dw6w57zhjc9wa38vicymql0g-jolt-unstable-2024-12-18/jolt-sdk", features = ["guest-std"] }
 
 wrapper_macro = { version = "0.1.0", path = "../wrapper_macro" }
+
+# The zkp dependency references a chosen guest in guests. It is included
+# (inserted here) by Nix. See zkvmLib.nix
diff --git a/zkvms/jolt/host/src/main.rs b/zkvms/jolt/host/src/main.rs
index b47966c..54a6e61 100644
--- a/zkvms/jolt/host/src/main.rs
+++ b/zkvms/jolt/host/src/main.rs
@@ -9,6 +9,7 @@ pub fn main() {
     }
 
     let elf_path = std::env::var("ELF_PATH").expect("ELF PATH is missing");
+    // guest_closures are generated by (Jolt's) wrapper_macro
     let (prove_guest, verify_guest) = guest::guest_closures(elf_path);
 
     match run_info.run_type {
diff --git a/zkvms/jolt/wrapper_macro/src/lib.rs b/zkvms/jolt/wrapper_macro/src/lib.rs
index 10e03b0..7631950 100644
--- a/zkvms/jolt/wrapper_macro/src/lib.rs
+++ b/zkvms/jolt/wrapper_macro/src/lib.rs
@@ -6,7 +6,42 @@ use quote::quote;
 mod parse_fn;
 use crate::parse_fn::{ split_fn, args_split, args_divide, group_streams };
 
-
+/// Create a set of three helper functions.
+///
+/// First a function called "guest" with the same arguments and return types
+/// as our specific guest's entrypoint function, which calls the aforementioned
+/// entrypoint function.
+///
+/// In essence, we create a wrapper function around the entrypoint, which also
+/// has the required `jolt::provable` attribute.
+///
+/// Second is a `guests_closure` function, almost identical to Jolt's
+/// `build_guest` function, which takes an already built guest ELF.
+/// Since we're following Jolt's design, it uses a third generated function,
+/// called `preprocess_guest_elf`.
+///
+/// # Usage
+///
+/// Inside Jolt's guest (excluding the `entrypoint_expr` call):
+///
+/// ```rust
+/// make_wrapper!{fn main(...) -> ...}
+/// ```
+///
+/// # Example output
+///
+/// ```rust
+/// #[jolt::provable(max_input_size = 100000)]
+/// fn guest(...) -> ... {
+///     zkp::main(...)
+/// }
+///
+/// #[cfg(all(not(target_arch = "wasm32"), not(feature = "guest")))]
+/// pub fn guest_closures(elf_path: String) -> (...) { ..... }
+///
+/// #[cfg(all(not(target_arch = "wasm32"), not(feature = "guest")))]
+/// pub fn preprocess_guest_elf(elf_path: String) -> (...) { ..... }
+/// ```
 #[proc_macro]
 pub fn make_wrapper(item: TokenStream) -> TokenStream {
     let (name, args, ret) = split_fn(&item);