Add some comments to fizzy.h

Author: gumb0

include/fizzy/fizzy.h

@@ -11,46 +11,82 @@
 extern "C" {
 #endif
 
-bool fizzy_validate(const uint8_t* wasm_binary, size_t wasm_binary_size);
-
+/// The opaque data type representing a module.
 struct fizzy_module;
 
-struct fizzy_module* fizzy_parse(const uint8_t* wasm_binary, size_t wasm_binary_size);
-
-void fizzy_free_module(struct fizzy_module*);
+/// The opaque data type representing an instance (instantiated module).
+struct fizzy_instance;
 
+/// The data type representing numeric values.
+///
+/// i64 member is used to represent values of both i32 and i64 type.
 union fizzy_value
 {
     uint64_t i64;
     float f32;
     double f64;
 };
 
+/// Result of execution of a function.
 typedef struct fizzy_execution_result
 {
+    /// Whether execution ended with a trap.
     bool trapped;
+    /// Whether function returned a value. Valid only if trapped == false
     bool has_value;
+    /// Value returned from a function. Valid only if has_value == true
     union fizzy_value value;
 } fizzy_execution_result;
 
-struct fizzy_instance;
 
+/// Pointer to external function.
+///
+/// @param context      Opaque pointer to execution context.
+/// @param instance     Pointer to module instance.
+/// @param args         Pointer to the argument array.
+/// @param args_size   Size of the  argument array.
+/// @param depth        Call stack depth.
 typedef struct fizzy_execution_result (*fizzy_external_fn)(void* context,
-    struct fizzy_instance* instance, const union fizzy_value* args, uint32_t cargs_size, int depth);
+    struct fizzy_instance* instance, const union fizzy_value* args, uint32_t args_size, int depth);
 
+/// External function.
 typedef struct fizzy_external_function
 {
     // TODO function type
+
+    /// Pointer to function.
     fizzy_external_fn function;
+    /// Opaque pointer to execution context, that will be passed to function.
     void* context;
 } fizzy_external_function;
 
-// Takes ownership of module.
+/// Validate binary module.
+bool fizzy_validate(const uint8_t* wasm_binary, size_t wasm_binary_size);
+
+/// Parse binary module.
+struct fizzy_module* fizzy_parse(const uint8_t* wasm_binary, size_t wasm_binary_size);
+
+/// Free resources associated with the module.
+void fizzy_free_module(struct fizzy_module* module);
+
+/// Instantiate a module.
+/// Takes ownership of module.
+///
+/// @param module                   Pointer to module.
+/// @param imported_functions       Pointer to the imported function array.
+/// @param imported_functions_size  Size of the imported function array.
 struct fizzy_instance* fizzy_instantiate(struct fizzy_module* module,
     const struct fizzy_external_function* imported_functions, uint32_t imported_functions_size);
 
-void fizzy_free_instance(struct fizzy_instance*);
+/// Free resources associated with the instance.
+void fizzy_free_instance(struct fizzy_instance* instance);
 
+/// Execute module function.
+///
+/// @param instance     Pointer to module instance.
+/// @param args         Pointer to the argument array.
+/// @param args_size   Size of the argument array.
+/// @param depth        Call stack depth.
 fizzy_execution_result fizzy_execute(struct fizzy_instance* instance, uint32_t func_idx,
     const union fizzy_value* args, uint32_t args_size, int depth);