From dac6bab2cd2b8acc38d5aa68e6b08776466a202a Mon Sep 17 00:00:00 2001
From: parazyd <parazyd@dyne.org>
Date: Fri, 7 Jan 2022 13:34:56 +0100
Subject: [PATCH] zkas: Document opcodes and types.

---
 zkas/src/opcode.rs | 12 ++++++++++++
 zkas/src/types.rs  |  9 +++++++++
 2 files changed, 21 insertions(+)

diff --git a/zkas/src/opcode.rs b/zkas/src/opcode.rs
index 83481e537..618f50718 100644
--- a/zkas/src/opcode.rs
+++ b/zkas/src/opcode.rs
@@ -4,24 +4,36 @@ use crate::types::Type;
 #[derive(Copy, Clone, Debug)]
 #[repr(u8)]
 pub enum Opcode {
+    /// Elliptic curve addition
     EcAdd = 0x00,
+    /// Elliptic curve multiplication
     EcMul = 0x01,
+    /// Elliptic curve multiplication with a Base field element
     EcMulBase = 0x02,
+    /// Elliptic curve multiplication with a u64 wrapped in a Scalar element
     EcMulShort = 0x03,
 
+    /// Get the x coordinate of an elliptic curve point
     EcGetX = 0x08,
+    /// Get the y coordinate of an elliptic curve point
     EcGetY = 0x09,
 
+    /// Poseidon hash of N elements
     PoseidonHash = 0x10,
 
+    /// Calculate merkle root given given a position, Merkle path, and an element
     CalculateMerkleRoot = 0x20,
 
+    /// Constrain a Base field element to a circuit's public input
     ConstrainInstance = 0xf0,
 
+    /// Intermediate opcode for the compiler, should never appear in the result
     Noop = 0xff,
 }
 
 impl Opcode {
+    /// Return a tuple of vectors of types that are accepted by a specific opcode
+    /// `r.0` is the return type(s) and `r.1` is the argument type(s).
     pub fn arg_types(&self) -> (Vec<Type>, Vec<Type>) {
         match self {
             // (return_type, opcode_arg_types)
diff --git a/zkas/src/types.rs b/zkas/src/types.rs
index 0d12d3a12..23e84438e 100644
--- a/zkas/src/types.rs
+++ b/zkas/src/types.rs
@@ -2,19 +2,28 @@
 #[derive(Copy, Clone, PartialEq, Debug)]
 #[repr(u8)]
 pub enum Type {
+    /// Elliptic curve point
     EcPoint = 0x00,
 
+    /// Elliptic curve fixed point (a constant)
     EcFixedPoint = 0x01,
 
+    /// Base field element
     Base = 0x10,
+    /// Array of Base field elements
     BaseArray = 0x11,
 
+    /// Scalar field element
     Scalar = 0x12,
+    /// Array of Scalar field elements
     ScalarArray = 0x13,
 
+    /// A Merkle path
     MerklePath = 0x20,
 
+    /// Unsigned 32-bit integer
     Uint32 = 0x30,
 
+    /// Intermediate type, should never appear in the result
     Dummy = 0xff,
 }