A little more documentation

sigma_compiler_core/src/lib.rs

@@ -7,7 +7,7 @@ use syn::{parse_quote, Expr, Ident, Token};
 /// The submodules that would be useful to have in the lower-level
 /// `sigma` crate are for now included as submodules of a local `sigma`
 /// module
-mod sigma {
+pub mod sigma {
     pub mod combiners;
     pub mod types;
 }
@@ -89,8 +89,9 @@ impl StructFieldList {
 
 /// An implementation of the
 /// [`VisitMut`](https://docs.rs/syn/latest/syn/visit_mut/trait.VisitMut.html)
-/// trait that massages the provided statements.  This massaging
-/// currently consists of:
+/// trait that massages the provided statements.
+///
+/// This massaging currently consists of:
 ///   - Changing equality from = to ==
 ///   - Changing any identifier `id` to either `params.id` or
 ///     `witness.id` depending on whether it is public or private
@@ -147,6 +148,17 @@ impl VisitMut for StatementFixup {
     }
 }
 
+/// The main function of this macro.
+///
+/// Parse the macro input with [`parse`](SigmaCompSpec) to produce
+/// a [`SigmaCompSpec`], and then pass that to this function to output
+/// the data structures and code for the ZKP protocol implementation.
+///
+/// If `emit_prover` is `true`, output the data structures and code for
+/// the prover side.  If `emit_verifier` is `true`, output the data
+/// structures and code for the verifier side.  (Typically both will be
+/// `true`, but you can set one to `false` if you don't need that side
+/// of the protocol.)
 pub fn sigma_compiler_core(
     spec: &SigmaCompSpec,
     emit_prover: bool,

sigma_compiler_core/src/syntax.rs

@@ -156,11 +156,29 @@ impl Parse for TaggedPoint {
     }
 }
 
+/// The [`SigmaCompSpec`] struct is the result of parsing the macro
+/// input.
 #[derive(Debug)]
 pub struct SigmaCompSpec {
+    /// An identifier for the name of the zero-knowledge protocol being
+    /// defined
     pub proto_name: Ident,
+
+    /// An identifier for the mathematical
+    /// [`PrimeGroup`](https://docs.rs/group/latest/group/prime/trait.PrimeGroup.html)
+    /// being used (if none is specified, it is assumed there is a
+    /// default type called `G` in scope that implements the
+    /// [`PrimeGroup`](https://docs.rs/group/latest/group/prime/trait.PrimeGroup.html)
+    /// trait)
     pub group_name: Ident,
+
+    /// A [`TaggedVarDict`] mapping variable names to their types
+    /// (`Scalar` or `Point`) and tags (e.g., `rand`, `pub`, `vec`,
+    /// `cind`, `const`)
     pub vars: TaggedVarDict,
+
+    /// A [`StatementTree`] representing the statements provided in the
+    /// macro invocation that are to be proved true in zero knowledge
     pub statements: StatementTree,
 }