More documentation on ops with AffineMap instantiations (#202)

Author: tim-hoffman

changelogs/unreleased/th__document_affine_arguments.yaml

@@ -0,0 +1,2 @@
+added:
+  - documentation

include/llzk/Dialect/Array/IR/Ops.td

@@ -172,9 +172,20 @@ def LLZK_CreateArrayOp
     ```
   }];
 
-  let arguments = (ins Variadic<ArrayElemType>:$elements,
+  // See `VerifySizesForMultiAffineOps` for more explanation of these arguments.
+  let arguments = (ins
+      // Elements to initialize the array. Length is either zero or equal to
+      // the length of the flattened/linearized result ArrayType.
+      Variadic<ArrayElemType>:$elements,
+      // List of AffineMap operand groups where each group provides the
+      // arguments to instantiate the next (left-to-right) AffineMap used as an
+      // array dimension in the result ArrayType.
       VariadicOfVariadic<Index, "mapOpGroupSizes">:$mapOperands,
+      // Within each group in '$mapOperands', denotes the number of values that
+      // are AffineMap "dimensional" arguments with the remaining values being
+      // AffineMap "symbolic" arguments.
       DefaultValuedAttr<DenseI32ArrayAttr, "{}">:$numDimsPerMap,
+      // Denotes the size of each variadic group in '$mapOperands'.
       DenseI32ArrayAttr:$mapOpGroupSizes);
   let results = (outs LLZK_ArrayType:$result);
 

include/llzk/Dialect/Function/IR/Ops.td

@@ -297,10 +297,18 @@ def CallOp : FunctionDialectOp<
     ```
   }];
 
+  // See `VerifySizesForMultiAffineOps` for more explanation of these arguments.
   let arguments = (ins SymbolRefAttr:$callee,
       Variadic<AnyLLZKType>:$argOperands,
+      // List of AffineMap operand groups where each group provides the
+      // arguments to instantiate the next (left-to-right) AffineMap used as a
+      // struct parameter in the result StructType.
       VariadicOfVariadic<Index, "mapOpGroupSizes">:$mapOperands,
+      // Within each group in '$mapOperands', denotes the number of values that
+      // are AffineMap "dimensional" arguments with the remaining values being
+      // AffineMap "symbolic" arguments.
       DefaultValuedAttr<DenseI32ArrayAttr, "{}">:$numDimsPerMap,
+      // Denotes the size of each variadic group in '$mapOperands'.
       DenseI32ArrayAttr:$mapOpGroupSizes);
   let results = (outs Variadic<AnyLLZKType>);
 

include/llzk/Dialect/Struct/IR/Ops.td

@@ -226,12 +226,20 @@ def LLZK_FieldReadOp
   }];
   let isRead = 1;
 
+  // See `VerifySizesForMultiAffineOps` for more explanation of these arguments.
   let arguments = (ins LLZK_StructType:$component,
       FlatSymbolRefAttr:$field_name,
       OptionalAttr<AnyAttrOf<[SymbolRefAttr, IndexAttr,
                               AffineMapAttr]>>:$tableOffset,
+      // List of AffineMap operand groups where each group provides the
+      // arguments to instantiate the next (left-to-right) AffineMap used in
+      // `tableOffset`.
       VariadicOfVariadic<Index, "mapOpGroupSizes">:$mapOperands,
+      // Within each group in '$mapOperands', denotes the number of values that
+      // are AffineMap "dimensional" arguments with the remaining values being
+      // AffineMap "symbolic" arguments.
       DefaultValuedAttr<DenseI32ArrayAttr, "{}">:$numDimsPerMap,
+      // Denotes the size of each variadic group in '$mapOperands'.
       DenseI32ArrayAttr:$mapOpGroupSizes);
   let results = (outs AnyLLZKType:$val);