docs: 📝 add documentation comments to the APIs (#1)

Co-authored-by: Rishit Chaudhary <12199011+rishitc@users.noreply.github.com>

src/builder/types/array_type.gleam

@@ -1,5 +1,6 @@
 import internal/structure/types.{type FieldType, ArrayType}
 
+/// Create a new ArrayType that holds values of the type specified by field_type
 pub fn new(field_type: FieldType) {
   ArrayType(field_type)
 }

src/builder/types/field_type.gleam

@@ -1,45 +1,66 @@
+//// https://webassembly.github.io/gc/core/syntax/types.html#syntax-fieldtype
+
 import internal/structure/types.{
   type RefType, type TypeIDX, ConcreteHeapType, Const, F32ValType, F64ValType,
   FieldType, HeapTypeRefType, I16StorageType, I32ValType, I64ValType,
   I8StorageType, RefTypeValType, TypeIDX, V128ValType, ValTypeStorageType, Var,
 }
 
+/// An immutable i8 type
 pub const i8 = FieldType(I8StorageType, Const)
 
+/// A mutable i8 type
 pub const i8_mut = FieldType(I8StorageType, Var)
 
+/// An immutable i16 type
 pub const i16 = FieldType(I16StorageType, Const)
 
+/// A mutable i16 type
 pub const i16_mut = FieldType(I16StorageType, Var)
 
+/// An immutable i32 type
 pub const i32 = FieldType(ValTypeStorageType(I32ValType), Const)
 
+/// A mutable i32 type
 pub const i32_mut = FieldType(ValTypeStorageType(I32ValType), Var)
 
+/// An immutable i64 type
 pub const i64 = FieldType(ValTypeStorageType(I64ValType), Const)
 
+/// A mutable i64 type
 pub const i64_mut = FieldType(ValTypeStorageType(I64ValType), Var)
 
+/// An immutable f32 type
 pub const f32 = FieldType(ValTypeStorageType(F32ValType), Const)
 
+/// A mutable f32 type
 pub const f32_mut = FieldType(ValTypeStorageType(F32ValType), Var)
 
+/// An immutable f64 type
 pub const f64 = FieldType(ValTypeStorageType(F64ValType), Const)
 
+/// A mutable f64 type
 pub const f64_mut = FieldType(ValTypeStorageType(F64ValType), Var)
 
+/// An immutable v128 type
 pub const v128 = FieldType(ValTypeStorageType(V128ValType), Const)
 
+/// A mutable v128 type
 pub const v128_mut = FieldType(ValTypeStorageType(V128ValType), Var)
 
+/// Create an immutable FieldType from the given RefType classifier
 pub fn from_ref_type(ref_type: RefType) {
   FieldType(ValTypeStorageType(RefTypeValType(ref_type)), Const)
 }
 
+/// Create a mutable FieldType from the given RefType classifier
 pub fn from_ref_type_mut(ref_type: RefType) {
   FieldType(ValTypeStorageType(RefTypeValType(ref_type)), Var)
 }
 
+/// Create an immutable non-nullable field of type indexed by type_idx
+///
+/// Note: The TypeIDX cannot be a RecTypeIDX or DefTypeReference
 pub fn from_type_index(type_idx: TypeIDX) {
   FieldType(
     ValTypeStorageType(
@@ -49,6 +70,9 @@ pub fn from_type_index(type_idx: TypeIDX) {
   )
 }
 
+/// Create a mutable non-nullable field of type indexed by type_idx
+///
+/// Note: The TypeIDX cannot be a RecTypeIDX or DefTypeReference
 pub fn from_type_index_mut(type_idx: TypeIDX) {
   FieldType(
     ValTypeStorageType(
@@ -58,6 +82,9 @@ pub fn from_type_index_mut(type_idx: TypeIDX) {
   )
 }
 
+/// Create an immutable nullable field of type indexed by type_idx
+///
+/// Note: The TypeIDX cannot be a RecTypeIDX or DefTypeReference
 pub fn from_type_index_nullable(type_idx: TypeIDX) {
   FieldType(
     ValTypeStorageType(
@@ -67,6 +94,9 @@ pub fn from_type_index_nullable(type_idx: TypeIDX) {
   )
 }
 
+/// Create a mutable nullable field of type indexed by type_idx
+///
+/// Note: The TypeIDX cannot be a RecTypeIDX or DefTypeReference
 pub fn from_type_index_nullable_mut(type_idx: TypeIDX) {
   FieldType(
     ValTypeStorageType(

src/builder/types/func_type.gleam

@@ -1,6 +1,8 @@
 import internal/finger_tree
 import internal/structure/types.{type ValType, FuncType}
 
+/// Create a FuncType from the given list of parameter types and result types
+/// https://webassembly.github.io/gc/core/syntax/types.html#function-types
 pub fn new(param_types: List(ValType), result_types: List(ValType)) {
   FuncType(
     finger_tree.from_list(param_types),

src/builder/types/global.gleam

@@ -1,10 +1,16 @@
-import internal/structure/types.{type Expr, type ValType, Global, GlobalType, Const, Var}
+//// https://webassembly.github.io/gc/core/syntax/modules.html#globals
 
+import internal/structure/types.{
+  type Expr, type ValType, Const, Global, GlobalType, Var,
+}
+
+/// Create an immutable `Global` with the given `ValType` and init `Expr`
 pub fn new(type_: ValType, expr: Expr) {
   let type_ = GlobalType(type_, Const)
   Global(type_, expr)
 }
 
+/// Create a mutable `Global` with the given `ValType` and init `Expr`
 pub fn new_mutable(type_: ValType, expr: Expr) {
   let type_ = GlobalType(type_, Var)
   Global(type_, expr)

src/builder/types/ref_type.gleam

@@ -4,6 +4,8 @@ import internal/structure/types.{
   NoFuncRefType, NoneRefType, StructRefType,
 }
 
+// Create a RefType from the given HeapType classifier and nullable option
+// https://webassembly.github.io/gc/core/syntax/types.html#reference-types
 pub fn from_heap_type(heap_type: HeapType, nullable: Bool) -> RefType {
   HeapTypeRefType(heap_type, nullable)
 }

src/builder/types/struct_type.gleam

@@ -7,123 +7,124 @@ import internal/structure/types.{
 }
 
 /// Create an empty Struct type
+/// https://webassembly.github.io/gc/core/syntax/types.html#aggregate-types
 pub fn new() {
   StructType(finger_tree.empty)
 }
 
-/// Add an immutable i8 field to the struct
+/// Add an immutable `i8` field to the struct
 pub fn i8_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(I8StorageType, Const)),
   )
 }
 
-/// Add a mutable i8 field to the struct
+/// Add a mutable `i8` field to the struct
 pub fn i8_mut_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(I8StorageType, Var)),
   )
 }
 
-/// Add an immutable i16 field to the struct
+/// Add an immutable `i16` field to the struct
 pub fn i16_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(I16StorageType, Const)),
   )
 }
 
-/// Add a mutable i16 field to the struct
+/// Add a mutable `i16` field to the struct
 pub fn i16_mut_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(I16StorageType, Var)),
   )
 }
 
-/// Add an immutable i32 field to the struct
+/// Add an immutable `i32` field to the struct
 pub fn i32_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(I32ValType), Const)),
   )
 }
 
-/// Add a mutable i32 field to the struct
+/// Add a mutable `i32` field to the struct
 pub fn i32_mut_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(I32ValType), Var)),
   )
 }
 
-/// Add an immutable i64 field to the struct
+/// Add an immutable `i64` field to the struct
 pub fn i64_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(I64ValType), Const)),
   )
 }
 
-/// Add a mutable i64 field to the struct
+/// Add a mutable `i64` field to the struct
 pub fn i64_mut_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(I64ValType), Var)),
   )
 }
 
-/// Add an immutable f32 field to the struct
+/// Add an immutable `f32` field to the struct
 pub fn f32_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(F32ValType), Const)),
   )
 }
 
-/// Add a mutable f32 field to the struct
+/// Add a mutable `f32` field to the struct
 pub fn f32_mut_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(F32ValType), Var)),
   )
 }
 
-/// Add an immutable f64 field to the struct
+/// Add an immutable `f64` field to the struct
 pub fn f64_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(F64ValType), Const)),
   )
 }
 
-/// Add a mutable f64 field to the struct
+/// Add a mutable `f64` field to the struct
 pub fn f64_mut_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(F64ValType), Var)),
   )
 }
 
-/// Add an immutable v128 field to the struct
+/// Add an immutable `v128` field to the struct
 pub fn v128_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(V128ValType), Const)),
   )
 }
 
-/// Add a mutable v128 field to the struct
+/// Add a mutable `v128` field to the struct
 pub fn v128_mut_field(struct_type: StructType) {
   StructType(
     struct_type.ft
     |> finger_tree.push(FieldType(ValTypeStorageType(V128ValType), Var)),
   )
 }
 
-/// Add an immutable RefType field to the struct
+/// Add an immutable `RefType` field to the struct
 pub fn from_ref_type_field(struct_type: StructType, ref_type: RefType) {
   StructType(
     struct_type.ft
@@ -134,7 +135,7 @@ pub fn from_ref_type_field(struct_type: StructType, ref_type: RefType) {
   )
 }
 
-/// Add a mutable RefType field to the struct
+/// Add a mutable `RefType` field to the struct
 pub fn from_ref_type_mut_field(struct_type: StructType, ref_type: RefType) {
   StructType(
     struct_type.ft
@@ -145,6 +146,9 @@ pub fn from_ref_type_mut_field(struct_type: StructType, ref_type: RefType) {
   )
 }
 
+/// Add an immutable non-nullable field of type indexed by type_idx to the struct
+///
+/// Note: The `TypeIDX` cannot be a `RecTypeIDX` or `DefTypeReference`
 pub fn from_type_index_field(struct_type: StructType, type_idx: TypeIDX) {
   StructType(
     struct_type.ft
@@ -157,6 +161,9 @@ pub fn from_type_index_field(struct_type: StructType, type_idx: TypeIDX) {
   )
 }
 
+/// Add a mutable non-nullable field of type indexed by type_idx to the struct
+///
+/// Note: The `TypeIDX` cannot be a `RecTypeIDX` or `DefTypeReference`
 pub fn from_type_index_mut_field(struct_type: StructType, type_idx: TypeIDX) {
   StructType(
     struct_type.ft
@@ -169,6 +176,9 @@ pub fn from_type_index_mut_field(struct_type: StructType, type_idx: TypeIDX) {
   )
 }
 
+/// Add an immutable nullable field of type indexed by type_idx to the struct
+///
+/// Note: The `TypeIDX` cannot be a `RecTypeIDX` or `DefTypeReference`
 pub fn from_type_index_nullable_field(
   struct_type: StructType,
   type_idx: TypeIDX,
@@ -184,6 +194,9 @@ pub fn from_type_index_nullable_field(
   )
 }
 
+/// Add a mutable nullable field of type indexed by type_idx to the struct
+///
+/// Note: The `TypeIDX` cannot be a `RecTypeIDX` or `DefTypeReference`
 pub fn from_type_index_nullable_mut_field(
   struct_type: StructType,
   type_idx: TypeIDX,

src/builder/types/table.gleam

@@ -3,11 +3,13 @@ import internal/structure/types.{
   type Expr, type Limits, type RefType, type Table, Table, TableType,
 }
 
+/// Create a new Table with the given `RefType` classifier and `Limits`
 pub fn new(ref_type: RefType, limits: Limits) {
   let type_ = TableType(ref_type, limits)
   Table(type_, None)
 }
 
+/// Create a new Table with the given `RefType` classifier, `Limits` and init `Expr`
 pub fn new_with_initializer(ref_type: RefType, limits: Limits, expr: Expr) {
   let type_ = TableType(ref_type, limits)
   Table(type_, Some(expr))

src/builder/types/val_type.gleam

@@ -3,18 +3,25 @@ import internal/structure/types.{
   RefTypeValType, V128ValType,
 }
 
+/// A ValType of type `v128`
 pub const v128 = V128ValType
 
+/// A ValType of type `i32`
 pub const i32 = I32ValType
 
+/// A ValType of type `i64`
 pub const i64 = I64ValType
 
+/// A ValType of type `f32`
 pub const f32 = F32ValType
 
+/// A ValType of type `f64`
 pub const f64 = F64ValType
 
+/// A ValType of type `bot`
 pub const bot = BotValType
 
+/// Create a ValType from the given `RefType` classifier
 pub fn from_ref_type(ref_type: RefType) {
   RefTypeValType(ref_type)
 }

src/internal/binary/types.gleam

@@ -906,7 +906,7 @@ pub fn decode_cast_flags(bits: BitArray) {
 
 /// Cast flags define the behavior of the `cast` instruction, defining which
 /// heap type operands are nullable.
-/// 
+///
 /// Please see the control instructions for more information:
 /// https://webassembly.github.io/gc/core/binary/instructions.html#control-instructions
 pub fn encode_cast_flags(builder: BytesBuilder, cast_flags: #(Bool, Bool)) {