add comments

zokrates_core/src/absy/from_ast.rs

@@ -451,6 +451,10 @@ impl<'ast, T: Field> From<pest::PostfixExpression<'ast>> for absy::ExpressionNod
         let id_str = expression.id.span.as_str();
         let id = absy::ExpressionNode::from(expression.id);
 
+        // pest::PostFixExpression contains an array of "accesses": `a(34)[42]` is represented as `[a, [Call(34), Select(42)]]`, but absy::ExpressionNode
+        // is recursive, so it is `Select(Call(a, 34), 42)`. We apply this transformation here
+
+        // we start with the id, and we fold the array of accesses by wrapping the current value
         expression.accesses.into_iter().fold(id, |acc, a| match a {
             pest::Access::Call(a) => match acc.value {
                 absy::Expression::Identifier(_) => absy::Expression::FunctionCall(

zokrates_core/src/semantics.rs

@@ -662,7 +662,9 @@ impl<'ast> Checker<'ast> {
                         let size = e.size();
                         match e.into_inner() {
                             // if we're doing a spread over an inline array, we return the inside of the array: ...[x, y, z] == x, y, z
+                            // this is not strictly needed, but it makes spreads memory linear rather than quadratic
                             ArrayExpressionInner::Value(v) => Ok(v),
+                            // otherwise we return a[0], ..., a[a.size() -1 ]
                             e => Ok((0..size)
                                 .map(|i| match &ty {
                                     Type::FieldElement => FieldElementExpression::Select(

zokrates_core/src/typed_absy/mod.rs

@@ -541,6 +541,11 @@ pub enum BooleanExpression<'ast, T: Field> {
     ),
 }
 
+/// An expression of type `array`
+/// # Remarks
+/// * Contrary to basic types which represented as enums, we wrap an enum `ArrayExpressionInner` in a struct in order to keep track of the type (content and size)
+/// of the array. Only using an enum would require generics, which would propagate up to TypedExpression which we want to keep simple, hence this "runtime"
+/// type checking
 #[derive(Clone, PartialEq, Hash, Eq)]
 pub struct ArrayExpression<'ast, T: Field> {
     size: usize,
@@ -593,7 +598,9 @@ impl<'ast, T: Field> ArrayExpression<'ast, T> {
 }
 
 // Downcasts
-
+// Due to the fact that we keep TypedExpression simple, we end up with ArrayExpressionInner::Value whose elements are any TypedExpression, but we enforce by
+// construction that these elements are of the type declared in the corresponding ArrayExpression. As we know this by construction, we can downcast the TypedExpression to the correct type
+// ArrayExpression { type: Type::FieldElement, size: 42, inner: [TypedExpression::FieldElement(FieldElementExpression), ...]} <- the fact that inner only contains field elements is not enforced by the rust type system
 impl<'ast, T: Field> TryFrom<TypedExpression<'ast, T>> for FieldElementExpression<'ast, T> {
     type Error = ();