docs(zkvms/zkwasm): Add detailed documentation comments

1 files changed, 45 insertions, 1 deletions

diff --git a/zkvms/zkwasm/wrapper_macro/src/lib.rs b/zkvms/zkwasm/wrapper_macro/src/lib.rs
index 301ba60..8bdb581 100644
--- a/zkvms/zkwasm/wrapper_macro/src/lib.rs
+++ b/zkvms/zkwasm/wrapper_macro/src/lib.rs
@@ -5,6 +5,12 @@ mod parse_fn;
 use crate::parse_fn::{ split_fn, args_divide_grouped, args_divide_public, group_streams };
 use toml::Table;
 
+/// Extends an out TokenStream with `let` directives for all patterns (and
+/// types). readfn specifies wether the input is public or private.
+///
+/// Each `let` binding calls the read! macro (defined in zkWasm wrapper_macro
+/// crate), feeding it an autogenerated "type note", which is then used to
+/// "deserialize" the input.
 fn insert_reads(out: &mut TokenStream, patterns: &Vec<TokenStream>, types: &Vec<TokenStream>, readfn: &str) {
     for i in 0..patterns.len() {
         let type_note: String = format!("{}", types[i])
@@ -14,6 +20,32 @@ fn insert_reads(out: &mut TokenStream, patterns: &Vec<TokenStream>, types: &Vec<
     }
 }
 
+/// Creates a body, which reads all inputs, stores them in variables, then
+/// executes the entrypoint function with those arguments and writes the
+/// result.
+///
+/// Inputs are read via the read! macro (defined in the zkWasm wrapper_macro
+/// crate). Their public status is dependent on `default_public_input.toml`.
+///
+/// # Usage
+///
+/// Inside zkWasm's guest (excluding the `entrypoint_expr` call):
+///
+/// ```rust
+/// make_wrapper!{fn main(...) -> ...}
+/// ```
+///
+/// # Example output
+///
+/// ```rust
+/// {
+///     let ... : ... = read!(... ...);
+///     let ... : ... = read!(... ...);
+///     ...
+///     let result = zkp::main(..., ..., ...);
+///     write(result as u64);
+/// }
+/// ```
 #[proc_macro]
 pub fn make_wrapper(item: TokenStream) -> TokenStream {
     let (name, args, ret) = split_fn(&item);
@@ -33,7 +65,6 @@ pub fn make_wrapper(item: TokenStream) -> TokenStream {
 
     out.extend(format!("
         let result = zkp::{}{};
-        assert(result);
         write(result as u64);
     ", name, ts_patterns).parse::<TokenStream>());
 
@@ -129,6 +160,19 @@ fn return_tuple(readfn: &TokenTree, inner: &TokenStream) -> TokenStream {
     ").parse().unwrap()
 }
 
+/// Creates a body which returns a value of the type, defined as a "type note"
+/// argument.
+///
+/// The host "serializes" all input data by flattening it as a series of
+/// integers. This function, in turn, unflattens the input, by reading integers
+/// multiple times and combining them in the appropriate structures.
+///
+/// It takes two arguments, separated by a space. The first is a string "type
+/// note" and the second is the name of the read function (either read_private
+/// or read_public).
+///
+/// The type note is similar to a print!("{:?}") output, however angled braces
+/// are square.
 #[proc_macro]
 pub fn read(item: TokenStream) -> TokenStream {
     let mut parts = item.clone().into_iter();