From d69e4e7f11ff45e82dace6b861aebe665dccb303 Mon Sep 17 00:00:00 2001
From: Kamen Mladenov <kamen@syndamia.com>
Date: Mon, 10 Feb 2025 14:06:57 +0200
Subject: docs(zkvms/risc0): Add detailed documentation comments

---
 zkvms/risc0/guest/Cargo.toml         |  7 ++++++-
 zkvms/risc0/host/src/main.rs         |  1 +
 zkvms/risc0/wrapper_macro/src/lib.rs | 26 ++++++++++++++++++++++++++
 3 files changed, 33 insertions(+), 1 deletion(-)

(limited to 'zkvms')

diff --git a/zkvms/risc0/guest/Cargo.toml b/zkvms/risc0/guest/Cargo.toml
index 4495781..08fda0b 100644
--- a/zkvms/risc0/guest/Cargo.toml
+++ b/zkvms/risc0/guest/Cargo.toml
@@ -1,10 +1,15 @@
 [package]
 name = "guest"
+description = "RISC0's specific guest crate, which includes the chosen guest in guests"
 version = "0.1.0"
 edition = "2021"
 
 [workspace]
 
 [dependencies]
-wrapper_macro = { version = "0.1.0", path = "../wrapper_macro" }
 risc0-zkvm = { path = "/nix/store/l1rxg23rrrdwi9cf6rc82mqavklvqc18-risc0-unstable-2024-12-21/risc0/zkvm", default-features = false, features = ['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/risc0/host/src/main.rs b/zkvms/risc0/host/src/main.rs
index 624b3f2..6428d84 100644
--- a/zkvms/risc0/host/src/main.rs
+++ b/zkvms/risc0/host/src/main.rs
@@ -6,6 +6,7 @@ use hex::FromHex;
 // https://github.com/risc0/risc0/blob/881e512732eca72849b2d0e263a1242aba3158af/risc0/build/src/lib.rs#L280-L284
 static HELLO_GUEST_ELF: &[u8] = include_bytes!("./guest");
 // https://github.com/risc0/risc0/blob/881e512732eca72849b2d0e263a1242aba3158af/risc0/build/src/lib.rs#L255
+// Generated by Nix, see zkvms/risc0/default.nix
 static HELLO_GUEST_ID: &str = env!("GUEST_ID");
 
 fn build_env(input: &Input) -> ExecutorEnv {
diff --git a/zkvms/risc0/wrapper_macro/src/lib.rs b/zkvms/risc0/wrapper_macro/src/lib.rs
index 22afa44..24eddd4 100644
--- a/zkvms/risc0/wrapper_macro/src/lib.rs
+++ b/zkvms/risc0/wrapper_macro/src/lib.rs
@@ -4,6 +4,32 @@ use proc_macro::TokenStream;
 mod parse_fn;
 use crate::parse_fn::{ split_fn, args_split, args_divide_public, args_divide_grouped };
 
+/// Create a body, which reads all inputs, stores them in variables, then
+/// commits the ones, defined as public in `default_public_input.toml` to the
+/// journal and finally executes the guest entrypoint function with those
+/// arguments, committing its output.
+///
+/// # Usage
+///
+/// Inside RISC0's guest (excluding the `entrypoint_expr` call):
+///
+/// ```rust
+/// make_wrapper!{fn main(...) -> ...}
+/// ```
+///
+/// # Example output
+///
+/// ```rust
+/// {
+///     let ... : ... = read();
+///     let ... : ... = read();
+///     ...
+///     commit(&...);
+///     commit(&...);
+///     ...
+///     commit(&zkp::main(..., ..., ...));
+/// }
+/// ```
 #[proc_macro]
 pub fn make_wrapper(item: TokenStream) -> TokenStream {
     let (name, args, ret) = split_fn(&item);
-- 
cgit v1.2.3