docs(zkvms_host_io): Add detailed documentation comments

2 files changed, 85 insertions, 1 deletions

diff --git a/zkvms_host_io/input_macros/src/lib.rs b/zkvms_host_io/input_macros/src/lib.rs
index e2982ca..465a9b4 100644
--- a/zkvms_host_io/input_macros/src/lib.rs
+++ b/zkvms_host_io/input_macros/src/lib.rs
@@ -4,6 +4,8 @@ use proc_macro::TokenStream;
 mod parse_fn;
 use crate::parse_fn::{ args_split, args_split_public, args_divide, args_divide_public, group_streams };
 
+/// Parses the `guests/type.txt` type note, created from the guest
+/// Returns a tuple of the arguments group and the return type
 fn get_types() -> (TokenStream, TokenStream) {
     let types: Vec<&str> = include_str!("../../../guests/type.txt")
         .split('\n')
@@ -13,6 +15,54 @@ fn get_types() -> (TokenStream, TokenStream) {
 
 static DERIVES: &str = "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]";
 
+/// Creates an Output type def and three Input structures from the guest
+/// type.txt file.
+///
+/// # Usage
+///
+/// Inside zkvms_host_io:
+///
+/// ```rust
+/// input_macros::generate_output_type_input_struct!();
+/// ```
+///
+/// # Example output
+///
+/// ```rust
+/// pub type Output = (... ...);
+///
+/// #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+/// pub struct PublicInput {
+///     pub ...: ...,
+///     pub ...: ...,
+///     ...
+/// }
+///
+/// #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+/// pub struct PrivateInput {
+///     pub ...: ...,
+///     pub ...: ...,
+///     ...
+/// }
+///
+/// #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+/// pub struct Input {
+///     pub ...: ...,
+///     pub ...: ...,
+///     ...
+/// }
+///
+/// // Converts Input to a tuple
+/// impl From<Input> for (...) {
+///     fn from(input: Input) -> (...) {
+///         (
+///             input....,
+///             input....,
+///             ...
+///         )
+///     }
+/// }
+/// ```
 #[proc_macro]
 pub fn generate_output_type_input_struct(_: TokenStream) -> TokenStream {
     let (args, ret) = get_types();
@@ -65,6 +115,8 @@ pub fn generate_output_type_input_struct(_: TokenStream) -> TokenStream {
     (output_type + &public_input_type + &private_input_type + &struct_def).parse::<TokenStream>().unwrap()
 }
 
+/// Repeats the given item as many times as fields there are, while replacing
+/// all `.yield` occurences with the fields value (field name).
 fn foreach_field(item: TokenStream, fields: Vec<TokenStream>) -> TokenStream {
     let expr = format!("{}", item);
     let mut out = String::new();
@@ -75,6 +127,9 @@ fn foreach_field(item: TokenStream, fields: Vec<TokenStream>) -> TokenStream {
     out.parse::<TokenStream>().unwrap()
 }
 
+/// Repeats the given code as many times as fields there are in the Input
+/// struct, while replacing all `.yield` occurences with the concrete
+/// field name.
 #[proc_macro]
 pub fn foreach_input_field(item: TokenStream) -> TokenStream {
     let (args, _) = get_types();
@@ -83,6 +138,9 @@ pub fn foreach_input_field(item: TokenStream) -> TokenStream {
     foreach_field(item, arg_patterns)
 }
 
+/// Repeats the given code as many times as fields there are in the
+/// PublicInput struct, while replacing all `.yield` occurences with the
+/// concrete field name.
 #[proc_macro]
 pub fn foreach_public_input_field(item: TokenStream) -> TokenStream {
     let (args, _) = get_types();
@@ -96,6 +154,9 @@ pub fn foreach_public_input_field(item: TokenStream) -> TokenStream {
     foreach_field(item, public_patterns)
 }
 
+/// Repeats the given code as many times as fields there are in the
+/// PrivateInput struct, while replacing all `.yield` occurences with the
+/// concrete field name.
 #[proc_macro]
 pub fn foreach_private_input_field(item: TokenStream) -> TokenStream {
     let (args, _) = get_types();
@@ -109,6 +170,9 @@ pub fn foreach_private_input_field(item: TokenStream) -> TokenStream {
     foreach_field(item, private_patterns)
 }
 
+/// Assuming the `run_info` variable is present, it creates a block with all
+/// needed code to properly benchmark the input code, according to all command
+/// parameters.
 #[proc_macro]
 pub fn benchmarkable(item: TokenStream) -> TokenStream {
     format!(r#"
diff --git a/zkvms_host_io/src/lib.rs b/zkvms_host_io/src/lib.rs
index 3de8c5e..9448789 100644
--- a/zkvms_host_io/src/lib.rs
+++ b/zkvms_host_io/src/lib.rs
@@ -12,25 +12,32 @@ static DEFAULT_ENV: &str = include_str!(concat!(env!("INPUTS_DIR"), "/default.en
 #[derive(Parser, Debug)]
 #[command(version, about, long_about = None)]
 struct Cli {
-    /// What the ZKVM is going to do
+    /// ZKVM action (execute, prove, verify)
     run_type: RunType,
 
+    /// Path to private input file in (TOML format)
     private_input: Option<String>,
 
+    /// Path to public input file in (TOML format)
     public_input: Option<String>,
 
+    /// Enable benchmark timer and formatted output
     #[arg(short, long)]
     benchmark: bool,
 
+    /// Benchmark the given action multiple times
     #[arg(short, long, requires = "benchmark")]
     repeat: Option<usize>,
 
+    /// Output timings as milliseconds instead of seconds
     #[arg(short, long, requires = "benchmark")]
     millis: bool,
 
+    /// Put the benchmark's formatted output into a file of the given path
     #[arg(short, long, requires = "benchmark")]
     metrics_output: Option<String>,
 
+    /// Append the benchmark formatted output to the given file, instead of replacing it
     #[arg(short, long, requires = "benchmark")]
     append: bool,
 }
@@ -59,6 +66,14 @@ pub struct RunWith {
 }
 
 impl RunWith {
+    /// Returns a value of the given name from the environment,
+    /// default environment or the given constant, depending on which
+    /// one exists.
+    ///
+    /// If the variable is from either environments, the `then_apply`
+    /// function is executed to convert the String value.
+    ///
+    /// The default environment is taken from the guest's `default.env`
     pub fn env_then_or<T>(&self, variable_name: &str, then_apply: fn(String) -> Option<T>, else_const: T) -> T {
         env::var(variable_name)
             .ok()
@@ -70,6 +85,11 @@ impl RunWith {
                 .unwrap_or(else_const))
     }
 
+    /// Returns a value of the given name from the environment,
+    /// default environment or the given constant, depending on which
+    /// one exists.
+    ///
+    /// The default environment is taken from the guest's `default.env`
     pub fn env_or(&self, variable_name: &str, else_const: &str) -> String {
         self.env_then_or(variable_name, |x| Some(x), else_const.to_string())
     }