Document the rest of the C API (#1959)

This commit fills out documentation for all remaining functions in the C
API, and additionally enables "warn if undocumented" which will fail CI
since warnings are also treated as errors.

crates/c-api/doxygen.conf

@@ -778,7 +778,7 @@ WARNINGS               = YES
 # will automatically be disabled.
 # The default value is: YES.
 
-WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_UNDOCUMENTED   = YES
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some parameters
@@ -901,7 +901,9 @@ EXCLUDE_PATTERNS       =
 EXCLUDE_SYMBOLS        = assertions \
     WASM_DECLARE_* \
     WASM_API_EXTERN \
+    WASI_API_EXTERN \
     WASMTIME_DECLARE_OWN \
+    WASI_DECLARE_OWN \
     WASMTIME_CONFIG_PROP \
     own
 

crates/c-api/include/wasi.h

@@ -1,4 +1,8 @@
-// WASI C API
+/**
+ * \file wasi.h
+ *
+ * C API for WASI
+ */
 
 #ifndef WASI_H
 #define WASI_H
@@ -23,33 +27,158 @@ extern "C" {
   typedef struct wasi_##name##_t wasi_##name##_t; \
   WASI_API_EXTERN void wasi_##name##_delete(own wasi_##name##_t*);
 
-// WASI config
+/**
-
+ * \typedef wasi_config_t
+ * \brief Convenience alias for #wasi_config_t
+ *
+ * \struct wasi_config_t
+ * \brief Opaque type used to create a #wasi_instance_t.
+ *
+ * \fn void wasi_config_delete(own wasi_config_t *);
+ * \brief Deletes a configuration object.
+ */
 WASI_DECLARE_OWN(config)
 
+/**
+ * \brief Creates a new empty configuration object.
+ *
+ * The caller is expected to deallocate the returned configuration
+ */
 WASI_API_EXTERN own wasi_config_t* wasi_config_new();
 
+/**
+ * \brief Sets the argv list for this configuration object.
+ *
+ * By default WASI programs have an empty argv list, but this can be used to
+ * explicitly specify what the argv list for the program is.
+ *
+ * The arguments are copied into the `config` object as part of this function
+ * call, so the `argv` pointer only needs to stay alive for this function call.
+ */
 WASI_API_EXTERN void wasi_config_set_argv(wasi_config_t* config, int argc, const char* argv[]);
+
+/**
+ * \brief Indicates that the argv list should be inherited from this process's
+ * argv list.
+ */
 WASI_API_EXTERN void wasi_config_inherit_argv(wasi_config_t* config);
 
+/**
+ * \brief Sets the list of environment variables available to the WASI instance.
+ *
+ * By default WASI programs have a blank environment, but this can be used to
+ * define some environment variables for them.
+ *
+ * It is required that the `names` and `values` lists both have `envc` entries.
+ *
+ * The env vars are copied into the `config` object as part of this function
+ * call, so the `names` and `values` pointers only need to stay alive for this
+ * function call.
+ */
 WASI_API_EXTERN void wasi_config_set_env(wasi_config_t* config, int envc, const char* names[], const char* values[]);
+
+/**
+ * \brief Indicates that the entire environment of the calling process should be
+ * inherited by this WASI configuration.
+ */
 WASI_API_EXTERN void wasi_config_inherit_env(wasi_config_t* config);
 
+/**
+ * \brief Configures standard input to be taken from the specified file.
+ *
+ * By default WASI programs have no stdin, but this configures the specified
+ * file to be used as stdin for this configuration.
+ *
+ * If the stdin location does not exist or it cannot be opened for reading then
+ * `false` is returned. Otherwise `true` is returned.
+ */
 WASI_API_EXTERN bool wasi_config_set_stdin_file(wasi_config_t* config, const char* path);
+
+/**
+ * \brief Configures this process's own stdin stream to be used as stdin for
+ * this WASI configuration.
+ */
 WASI_API_EXTERN void wasi_config_inherit_stdin(wasi_config_t* config);
 
+/**
+ * \brief Configures standard output to be written to the specified file.
+ *
+ * By default WASI programs have no stdout, but this configures the specified
+ * file to be used as stdout.
+ *
+ * If the stdout location could not be opened for writing then `false` is
+ * returned. Otherwise `true` is returned.
+ */
 WASI_API_EXTERN bool wasi_config_set_stdout_file(wasi_config_t* config, const char* path);
+
+/**
+ * \brief Configures this process's own stdout stream to be used as stdout for
+ * this WASI configuration.
+ */
 WASI_API_EXTERN void wasi_config_inherit_stdout(wasi_config_t* config);
 
+/**
+ * \brief Configures standard output to be written to the specified file.
+ *
+ * By default WASI programs have no stderr, but this configures the specified
+ * file to be used as stderr.
+ *
+ * If the stderr location could not be opened for writing then `false` is
+ * returned. Otherwise `true` is returned.
+ */
 WASI_API_EXTERN bool wasi_config_set_stderr_file(wasi_config_t* config, const char* path);
+
+/**
+ * \brief Configures this process's own stderr stream to be used as stderr for
+ * this WASI configuration.
+ */
 WASI_API_EXTERN void wasi_config_inherit_stderr(wasi_config_t* config);
 
+/**
+ * \brief Configures a "preopened directory" to be available to WASI APIs.
+ *
+ * By default WASI programs do not have access to anything on the filesystem.
+ * This API can be used to grant WASI programs access to a directory on the
+ * filesystem, but only that directory (its whole contents but nothing above it).
+ *
+ * The `path` argument here is a path name on the host filesystem, and
+ * `guest_path` is the name by which it will be known in wasm.
+ */
 WASI_API_EXTERN bool wasi_config_preopen_dir(wasi_config_t* config, const char* path, const char* guest_path);
 
-// WASI instance
+/**
-
+ * \typedef wasi_instance_t
+ * \brief Convenience alias for #wasi_instance_t
+ *
+ * \struct wasi_instance_t
+ * \brief Opaque type representing a WASI instance.
+ *
+ * \fn void wasi_instance_delete(own wasi_instance_t *);
+ * \brief Deletes an instance object.
+ */
 WASI_DECLARE_OWN(instance)
 
+/**
+ * \brief Creates a new WASI instance from the specified configuration.
+ *
+ * \param store the store which functions will be attached to
+ * \param name the WASI module name that is being instantiated, currently either
+ * `wasi_unstable` or `wasi_snapshot_preview`.
+ * \param config the configuration object which has settings for how WASI APIs
+ * will behave.
+ * \param trap a location, if `NULL` is returned, that contains information
+ * about why instantiation failed.
+ *
+ * \return a #wasi_instance_t owned by the caller on success or `NULL` on
+ * failure.
+ *
+ * Note that this function takes ownership of the `config` argument whether this
+ * function succeeds or not. Ownership of the #wasi_instance_t and #wasm_trap_t
+ * are transferred to the caller.
+ *
+ * With a #wasi_instance_t you'll likely call either
+ * #wasmtime_linker_define_wasi or #wasi_instance_bind_import afterwards.
+ */
 WASI_API_EXTERN own wasi_instance_t* wasi_instance_new(
   wasm_store_t* store,
   const char* name,
@@ -57,6 +186,19 @@ WASI_API_EXTERN own wasi_instance_t* wasi_instance_new(
   own wasm_trap_t** trap
 );
 
+/**
+ * \brief Extracts a matching item for the given import from a #wasi_instance_t.
+ *
+ * \param instance the WASI instance an export is extracted from
+ * \param import the desired import type that is being extracted, typically
+ * acquired from #wasm_module_imports.
+ *
+ * \return a #wasm_extern_t which can be used to satisfy the `import`
+ * requested, or `NULL` if the provided `instance` cannot satisfy `import`.
+ *
+ * This function does not take ownership of its arguments, and the lifetime of
+ * the #wasm_extern_t is tied to the #wasi_instance_t argument.
+ */
 WASI_API_EXTERN const wasm_extern_t* wasi_instance_bind_import(
   const wasi_instance_t* instance,
   const wasm_importtype_t* import
@@ -68,4 +210,4 @@ WASI_API_EXTERN const wasm_extern_t* wasi_instance_bind_import(
 }  // extern "C"
 #endif
 
-#endif  // #ifdef WASI_H
+#endif  // #ifdef WASI_H

crates/c-api/include/wasmtime.h

@@ -27,11 +27,18 @@ extern "C" {
   WASM_API_EXTERN void wasmtime_##name##_delete(own wasmtime_##name##_t*);
 
 /**
+ * \typedef wasmtime_error_t
+ * \brief Convenience alias for #wasmtime_error_t
+ *
+ * \struct wasmtime_error_t
  * \brief Errors generated by Wasmtime.
  *
  * This opaque type represents an error that happened as part of one of the
  * functions below. Errors primarily have an error message associated with them
  * at this time, which you can acquire by calling #wasmtime_error_message.
+ *
+ * \fn void wasmtime_error_delete(own wasmtime_error_t *);
+ * \brief Deletes an error.
  */
 WASMTIME_DECLARE_OWN(error)
 
@@ -48,74 +55,303 @@ WASM_API_EXTERN void wasmtime_error_message(
     own wasm_name_t *message
 );
 
+/**
+ * \brief Specifier for how Wasmtime will compile code, values are in
+ * #wasmtime_strategy_enum
+ */
 typedef uint8_t wasmtime_strategy_t;
+
+/**
+ * \brief Different ways that Wasmtime can compile WebAssembly
+ *
+ * The default value is #WASMTIME_STRATEGY_AUTO.
+ */
 enum wasmtime_strategy_enum { // Strategy
+  /// Wasmtime will automatically determine whether to use Cranelift or
+  /// Lightbeam, and currently it will always pick Cranelift. This default may
+  /// change over time though.
   WASMTIME_STRATEGY_AUTO,
+
+  /// Indicates that Cranelift will unconditionally use Cranelift to compile
+  /// WebAssembly code.
   WASMTIME_STRATEGY_CRANELIFT,
+
+  /// Indicates that Cranelift will unconditionally use Lightbeam to compile
+  /// WebAssembly code. Note that Lightbeam isn't always enabled at compile
+  /// time, and if that's the case an error will be returned.
   WASMTIME_STRATEGY_LIGHTBEAM,
 };
 
+/**
+ * \brief Specifier of what optimization level to use for generated JIT code.
+ *
+ * See #wasmtime_opt_level_enum for possible values.
+ */
 typedef uint8_t wasmtime_opt_level_t;
+
+/**
+ * \brief Different ways Wasmtime can optimize generated code.
+ *
+ * The default value is #WASMTIME_OPT_LEVEL_SPEED.
+ */
 enum wasmtime_opt_level_enum { // OptLevel
+  /// Generated code will not be optimized at all.
   WASMTIME_OPT_LEVEL_NONE,
+  /// Generated code will be optimized purely for speed.
   WASMTIME_OPT_LEVEL_SPEED,
+  /// Generated code will be optimized, but some speed optimizations are
+  /// disabled if they cause the generated code to be significantly larger.
   WASMTIME_OPT_LEVEL_SPEED_AND_SIZE,
 };
 
+/**
+ * \brief Different ways wasmtime can enable profiling JIT code.
+ *
+ * See #wasmtime_profiling_strategy_enum for possible values.
+ */
 typedef uint8_t wasmtime_profiling_strategy_t;
+
+/**
+ * \brief Different ways to profile JIT code.
+ *
+ * The default is #WASMTIME_PROFILING_STRATEGY_NONE.
+ */
 enum wasmtime_profiling_strategy_enum { // ProfilingStrategy
+  /// No profiling is enabled at runtime.
   WASMTIME_PROFILING_STRATEGY_NONE,
+  /// Linux's "jitdump" support in `perf` is enabled and when Wasmtime is run
+  /// under `perf` necessary calls will be made to profile generated JIT code.
   WASMTIME_PROFILING_STRATEGY_JITDUMP,
+  /// Support for VTune will be enabled and the VTune runtime will be informed,
+  /// at runtime, about JIT code.
+  ///
+  /// Note that this isn't always enabled at build time.
   WASMTIME_PROFILING_STRATEGY_VTUNE,
 };
 
 #define WASMTIME_CONFIG_PROP(ret, name, ty) \
     WASM_API_EXTERN ret wasmtime_config_##name##_set(wasm_config_t*, ty);
 
+/**
+ * \brief Configures whether DWARF debug information is constructed at runtime
+ * to describe JIT code.
+ *
+ * This setting is `false` by default. When enabled it will attempt to inform
+ * native debuggers about DWARF debugging information for JIT code to more
+ * easily debug compiled WebAssembly via native debuggers. This can also
+ * sometimes improve the quality of output when profiling is enabled.
+ */
 WASMTIME_CONFIG_PROP(void, debug_info, bool)
+
+/**
+ * \brief Enables WebAssembly code to be interrupted.
+ *
+ * This setting is `false` by default. When enabled it will enable getting an
+ * interrupt handle via #wasmtime_interrupt_handle_new which can be used to
+ * interrupt currently-executing WebAssembly code.
+ */
 WASMTIME_CONFIG_PROP(void, interruptable, bool)
+
+/**
+ * \brief Configures the maximum stack size, in bytes, that JIT code can use.
+ *
+ * This setting is 2MB by default. Configuring this setting will limit the
+ * amount of native stack space that JIT code can use while it is executing. If
+ * you're hitting stack overflow you can try making this setting larger, or if
+ * you'd like to limit wasm programs to less stack you can also configure this.
+ *
+ * Note that this setting is not interpreted with 100% precision. Additionally
+ * the amount of stack space that wasm takes is always relative to the first
+ * invocation of wasm on the stack, so recursive calls with host frames in the
+ * middle will all need to fit within this setting.
+ */
 WASMTIME_CONFIG_PROP(void, max_wasm_stack, size_t)
+
+/**
+ * \brief Configures whether the WebAssembly threading proposal is enabled.
+ *
+ * This setting is `false` by default.
+ *
+ * Note that threads are largely unimplemented in Wasmtime at this time.
+ */
 WASMTIME_CONFIG_PROP(void, wasm_threads, bool)
+
+/**
+ * \brief Configures whether the WebAssembly reference types proposal is
+ * enabled.
+ *
+ * This setting is `false` by default.
+ */
 WASMTIME_CONFIG_PROP(void, wasm_reference_types, bool)
+
+/**
+ * \brief Configures whether the WebAssembly SIMD proposal is
+ * enabled.
+ *
+ * This setting is `false` by default.
+ */
 WASMTIME_CONFIG_PROP(void, wasm_simd, bool)
+
+/**
+ * \brief Configures whether the WebAssembly bulk memory proposal is
+ * enabled.
+ *
+ * This setting is `false` by default.
+ */
 WASMTIME_CONFIG_PROP(void, wasm_bulk_memory, bool)
+
+/**
+ * \brief Configures whether the WebAssembly multi value proposal is
+ * enabled.
+ *
+ * This setting is `true` by default.
+ */
 WASMTIME_CONFIG_PROP(void, wasm_multi_value, bool)
+
+/**
+ * \brief Configures how JIT code will be compiled.
+ *
+ * This setting is #WASMTIME_STRATEGY_AUTO by default.
+ *
+ * If the compilation strategy selected could not be enabled then an error is
+ * returned.
+ */
 WASMTIME_CONFIG_PROP(wasmtime_error_t*, strategy, wasmtime_strategy_t)
+
+/**
+ * \brief Configures whether Cranelift's debug verifier is enabled.
+ *
+ * This setting in `false` by default.
+ *
+ * When cranelift is used for compilation this enables expensive debug checks
+ * within Cranelift itself to verify it's correct.
+ */
 WASMTIME_CONFIG_PROP(void, cranelift_debug_verifier, bool)
+
+/**
+ * \brief Configures Cranelift's optimization level for JIT code.
+ *
+ * This setting in #WASMTIME_OPT_LEVEL_SPEED by default.
+ */
 WASMTIME_CONFIG_PROP(void, cranelift_opt_level, wasmtime_opt_level_t)
+
+/**
+ * \brief Configures the profiling strategy used for JIT code.
+ *
+ * This setting in #WASMTIME_PROFILING_STRATEGY_NONE by default.
+ */
 WASMTIME_CONFIG_PROP(wasmtime_error_t*, profiler, wasmtime_profiling_strategy_t)
+
+/**
+ * \brief Configures the maximum size for memory to be considered "static"
+ *
+ * For more information see the Rust documentation at
+ * https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.static_memory_maximum_size.
+ */
 WASMTIME_CONFIG_PROP(void, static_memory_maximum_size, uint64_t)
+
+/**
+ * \brief Configures the guard region size for "static" memory.
+ *
+ * For more information see the Rust documentation at
+ * https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.static_memory_guard_size.
+ */
 WASMTIME_CONFIG_PROP(void, static_memory_guard_size, uint64_t)
+
+/**
+ * \brief Configures the guard region size for "dynamic" memory.
+ *
+ * For more information see the Rust documentation at
+ * https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.dynamic_memory_guard_size.
+ */
 WASMTIME_CONFIG_PROP(void, dynamic_memory_guard_size, uint64_t)
 
+/**
+ * \brief Enables Wasmtime's cache and loads configuration from the specified
+ * path.
+ *
+ * By default the Wasmtime compilation cache is disabled. The configuration path
+ * here can be `NULL` to use the default settings, and otherwise the argument
+ * here must be a file on the filesystem with TOML configuration -
+ * https://bytecodealliance.github.io/wasmtime/cli-cache.html.
+ *
+ * An error is returned if the cache configuration could not be loaded or if the
+ * cache could not be enabled.
+ */
 WASM_API_EXTERN wasmtime_error_t* wasmtime_config_cache_config_load(wasm_config_t*, const char*);
 
-///////////////////////////////////////////////////////////////////////////////
+/**
-
+ * \brief Converts from the text format of WebAssembly to to the binary format.
-// Converts from the text format of WebAssembly to to the binary format.
+ *
-//
+ * \param wat this it the input buffer with the WebAssembly Text Format inside of
-// * `wat` - this it the input buffer with the WebAssembly Text Format inside of
+ *   it. This will be parsed and converted to the binary format.
-//   it. This will be parsed and converted to the binary format.
+ * \param ret if the conversion is successful, this byte vector is filled in with
-// * `ret` - if the conversion is successful, this byte vector is filled in with
+ *   the WebAssembly binary format.
-//   the WebAssembly binary format.
+ *
-//
+ * \return a non-null error if parsing fails, or returns `NULL`. If parsing
-// Returns a non-null error if parsing fails, or returns `NULL`. If parsing
+ * fails then `ret` isn't touched.
-// fails then `ret` isn't touched.
+ *
+ * This function does not take ownership of `wat`, and the caller is expected to
+ * deallocate the returned #wasmtime_error_t and #wasm_byte_vec_t.
+ */
 WASM_API_EXTERN own wasmtime_error_t* wasmtime_wat2wasm(
     const wasm_byte_vec_t *wat,
     own wasm_byte_vec_t *ret
 );
 
-///////////////////////////////////////////////////////////////////////////////
+/**
-//
+ * \typedef wasmtime_linker_t
-// wasmtime_linker_t extension type, binding the `Linker` type in the Rust API
+ * \brief Convenience alias for #wasmtime_linker_t
-
+ *
+ * \struct wasmtime_linker_t
+ * \brief Object used to conveniently link together and instantiate wasm
+ * modules.
+ *
+ * This type corresponds to the `wasmtime::Linker` type in Rust. This
+ * Wasmtime-specific extension is intended to make it easier to manage a set of
+ * modules that link together, or to make it easier to link WebAssembly modules
+ * to WASI.
+ *
+ * A #wasmtime_linker_t is a higher level way to instantiate a module than
+ * #wasm_instance_new since it works at the "string" level of imports rather
+ * than requiring 1:1 mappings.
+ *
+ * \fn void wasmtime_linker_delete(own wasmtime_linker_t *);
+ * \brief Deletes a linker.
+ */
 WASMTIME_DECLARE_OWN(linker)
 
+/**
+ * \brief Creates a new linker which will link together objects in the specified
+ * store.
+ *
+ * This function does not take ownership of the store argument, and the caller
+ * is expected to delete the returned linker.
+ */
 WASM_API_EXTERN own wasmtime_linker_t* wasmtime_linker_new(wasm_store_t* store);
 
+/**
+ * \brief Configures whether this linker allows later definitions to shadow
+ * previous definitions.
+ *
+ * By default this setting is `false`.
+ */
 WASM_API_EXTERN void wasmtime_linker_allow_shadowing(wasmtime_linker_t* linker, bool allow_shadowing);
 
+/**
+ * \brief Defines a new item in this linker.
+ *
+ * \param linker the linker the name is being defined in.
+ * \param module the module name the item is defined under.
+ * \param name the field name the item is defined under
+ * \param item the item that is being defined in this linker.
+ *
+ * \return On success `NULL` is returned, otherwise an error is returned which
+ * describes why the definition failed.
+ *
+ * For more information about name resolution consult the [Rust
+ * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
+ */
 WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_define(
     wasmtime_linker_t *linker,
     const wasm_name_t *module,
@@ -123,17 +359,67 @@ WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_define(
     const wasm_extern_t *item
 );
 
+/**
+ * \brief Defines a WASI instance in this linker.
+ *
+ * \param linker the linker the name is being defined in.
+ * \param instance a previously-created WASI instance.
+ *
+ * \return On success `NULL` is returned, otherwise an error is returned which
+ * describes why the definition failed.
+ *
+ * For more information about name resolution consult the [Rust
+ * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
+ */
 WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_define_wasi(
     wasmtime_linker_t *linker,
     const wasi_instance_t *instance
 );
 
+/**
+ * \brief Defines an instance under the specified name in this linker.
+ *
+ * \param linker the linker the name is being defined in.
+ * \param name the module name to define `instance` under.
+ * \param instance a previously-created instance.
+ *
+ * \return On success `NULL` is returned, otherwise an error is returned which
+ * describes why the definition failed.
+ *
+ * This function will take all of the exports of the `instance` provided and
+ * defined them under a module called `name` with a field name as the export's
+ * own name.
+ *
+ * For more information about name resolution consult the [Rust
+ * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
+ */
 WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_define_instance(
     wasmtime_linker_t *linker,
     const wasm_name_t *name,
     const wasm_instance_t *instance
 );
 
+/**
+ * \brief Instantiates a #wasm_module_t with the items defined in this linker.
+ *
+ * \param linker the linker used to instantiate the provided module.
+ * \param module the module that is being instantiated.
+ * \param instance the returned instance, if successful.
+ * \param trap a trap returned, if the start function traps.
+ *
+ * \return One of three things can happen as a result of this function. First
+ * the module could be successfully instantiated and returned through
+ * `instance`, meaning the return value and `trap` are both set to `NULL`.
+ * Second the start function may trap, meaning the return value and `instance`
+ * are set to `NULL` and `trap` describes the trap that happens. Finally
+ * instantiation may fail for another reason, in which case an error is returned
+ * and `trap` and `instance` are set to `NULL`.
+ *
+ * This function will attempt to satisfy all of the imports of the `module`
+ * provided with items previously defined in this linker. If any name isn't
+ * defined in the linker than an error is returned. (or if the previously
+ * defined item is of the wrong type).
+ */
 WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_instantiate(
     const wasmtime_linker_t *linker,
     const wasm_module_t *module,
@@ -141,18 +427,59 @@ WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_instantiate(
     own wasm_trap_t **trap
 );
 
+/**
+ * \brief Defines automatic instantiations of a #wasm_module_t in this linker.
+ *
+ * \param linker the linker the module is being added to
+ * \param name the name of the module within the linker
+ * \param module the module that's being instantiated
+ *
+ * \return An error if the module could not be instantiated or added or `NULL`
+ * on success.
+ *
+ * This function automatically handles [Commands and
+ * Reactors](https://github.com/WebAssembly/WASI/blob/master/design/application-abi.md#current-unstable-abi)
+ * instantiation and initialization.
+ *
+ * For more information see the [Rust
+ * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#method.module).
+ */
 WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_module(
     const wasmtime_linker_t *linker,
     const wasm_name_t *name,
     const wasm_module_t *module
 );
 
+/**
+ * \brief Acquires the "default export" of the named module in this linker.
+ *
+ * \param linker the linker to load from
+ * \param name the name of the module to get the default export for
+ * \param func where to store the extracted default function.
+ *
+ * \return An error is returned if the default export could not be found, or
+ * `NULL` is returned and `func` is filled in otherwise.
+ *
+ * For more information see the [Rust
+ * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#method.get_default).
+ */
 WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_get_default(
     const wasmtime_linker_t *linker,
     const wasm_name_t *name,
     own wasm_func_t **func
 );
 
+/**
+ * \brief Loads an item by name from this linker.
+ *
+ * \param linker the linker to load from
+ * \param module the name of the module to get
+ * \param name the name of the field to get
+ * \param item where to store the extracted item
+ *
+ * \return An error is returned if the item isn't defined or has more than one
+ * definition, or `NULL` is returned and `item` is filled in otherwise.
+ */
 WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_get_one_by_name(
     const wasmtime_linker_t *linker,
     const wasm_name_t *module,
@@ -160,17 +487,55 @@ WASM_API_EXTERN own wasmtime_error_t* wasmtime_linker_get_one_by_name(
     own wasm_extern_t **item
 );
 
-///////////////////////////////////////////////////////////////////////////////
+/**
-//
+ * \brief Structure used to learn about the caller of a host-defined function.
-// wasmtime_caller_t extension, binding the `Caller` type in the Rust API
+ *
-
+ * This structure is the first argument of #wasmtime_func_callback_t and
+ * wasmtime_func_callback_with_env_t. The main purpose of this structure is for
+ * building a WASI-like API which can inspect the memory of the caller,
+ * regardless of the caller.
+ *
+ * This is intended to be a temporary API extension until interface types have
+ * become more prevalent. This is not intended to be supported until the end of
+ * time, but it will be supported so long as WASI requires it.
+ */
 typedef struct wasmtime_caller_t wasmtime_caller_t;
 
+/**
+ * \brief Callback signature for #wasmtime_func_new.
+ *
+ * This function is the same as #wasm_func_callback_t except that its first
+ * argument is a #wasmtime_caller_t which allows learning information about the
+ * caller.
+ */
 typedef own wasm_trap_t* (*wasmtime_func_callback_t)(const wasmtime_caller_t* caller, const wasm_val_t args[], wasm_val_t results[]);
+
+/**
+ * \brief Callback signature for #wasmtime_func_new_with_env.
+ *
+ * This function is the same as #wasm_func_callback_with_env_t except that its
+ * first argument is a #wasmtime_caller_t which allows learning information
+ * about the
+ * caller.
+ */
 typedef own wasm_trap_t* (*wasmtime_func_callback_with_env_t)(const wasmtime_caller_t* caller, void* env, const wasm_val_t args[], wasm_val_t results[]);
 
+/**
+ * \brief Creates a new host-defined function.
+ *
+ * This function is the same as #wasm_func_new, except the callback has the type
+ * signature #wasmtime_func_callback_t which gives a #wasmtime_caller_t as its
+ * first argument.
+ */
 WASM_API_EXTERN own wasm_func_t* wasmtime_func_new(wasm_store_t*, const wasm_functype_t*, wasmtime_func_callback_t callback);
 
+/**
+ * \brief Creates a new host-defined function.
+ *
+ * This function is the same as #wasm_func_new_with_env, except the callback
+ * has the type signature #wasmtime_func_callback_with_env_t which gives a
+ * #wasmtime_caller_t as its first argument.
+ */
 WASM_API_EXTERN own wasm_func_t* wasmtime_func_new_with_env(
   wasm_store_t* store,
   const wasm_functype_t* type,
@@ -179,68 +544,114 @@ WASM_API_EXTERN own wasm_func_t* wasmtime_func_new_with_env(
   void (*finalizer)(void*)
 );
 
+/**
+ * \brief Loads a #wasm_extern_t from the caller's context
+ *
+ * This function will attempt to look up the export named `name` on the caller
+ * instance provided. If it is found then the #wasm_extern_t for that is
+ * returned, otherwise `NULL` is returned.
+ *
+ * Note that this only works for exported memories right now for WASI
+ * compatibility.
+ */
 WASM_API_EXTERN own wasm_extern_t* wasmtime_caller_export_get(const wasmtime_caller_t* caller, const wasm_name_t* name);
 
-///////////////////////////////////////////////////////////////////////////////
+/**
-//
+ * \typedef wasmtime_interrupt_handle_t
-// wasmtime_interrupt_handle_t extension, allowing interruption of running wasm
+ * \brief Convenience alias for #wasmtime_interrupt_handle_t
-// modules.
+ *
-//
+ * \struct wasmtime_interrupt_handle_t
-// Note that `wasmtime_interrupt_handle_t` is safe to send to other threads and
+ * \brief A handle used to interrupt executing WebAssembly code.
-// interrupt/delete.
+ *
-//
+ * This structure is an opaque handle that represents a handle to a store. This
-// Also note that `wasmtime_interrupt_handle_new` may return NULL if interrupts
+ * handle can be used to remotely (from another thread) interrupt currently
-// are not enabled in `wasm_config_t`.
+ * executing WebAssembly code.
-
+ *
+ * This structure is safe to share from multiple threads.
+ *
+ * \fn void wasmtime_interrupt_handle_delete(own wasmtime_interrupt_handle_t *);
+ * \brief Deletes an interrupt handle.
+ */
 WASMTIME_DECLARE_OWN(interrupt_handle)
 
+/**
+ * \brief Creates a new interrupt handle to interrupt executing WebAssembly from
+ * the provided store.
+ *
+ * There are a number of caveats about how interrupt is handled in Wasmtime. For
+ * more information see the [Rust
+ * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Store.html#method.interrupt_handle).
+ *
+ * This function returns `NULL` if the store's configuration does not have
+ * interrupts enabled. See #wasmtime_config_interruptable_set.
+ */
 WASM_API_EXTERN own wasmtime_interrupt_handle_t *wasmtime_interrupt_handle_new(wasm_store_t *store);
 
+/**
+ * \brief Requests that WebAssembly code running in the store attached to this
+ * interrupt handle is interrupted.
+ *
+ * For more information about interrupts see #wasmtime_interrupt_handle_new.
+ *
+ * Note that this is safe to call from any thread.
+ */
 WASM_API_EXTERN void wasmtime_interrupt_handle_interrupt(wasmtime_interrupt_handle_t *handle);
 
-///////////////////////////////////////////////////////////////////////////////
+/**
-//
+ * \brief Attempts to extract a WASI-specific exit status from this trap.
-// Extensions to `wasm_trap_t`
+ *
-
+ * Returns `true` if the trap is a WASI "exit" trap and has a return status. If
-// Returns `true` if the trap is a WASI "exit" trap and has a return status. If
+ * `true` is returned then the exit status is returned through the `status`
-// `true` is returned then the exit status is returned through the `status`
+ * pointer. If `false` is returned then this is not a wasi exit trap.
-// pointer. If `false` is returned then this is not a wasi exit trap.
+ */
 WASM_API_EXTERN bool wasmtime_trap_exit_status(const wasm_trap_t*, int *status);
 
-///////////////////////////////////////////////////////////////////////////////
+/**
-//
+ * \brief Returns a human-readable name for this frame's function.
-// Extensions to `wasm_frame_t`
+ *
-
+ * This function will attempt to load a human-readable name for function this
+ * frame points to. This function may return `NULL`.
+ *
+ * The lifetime of the returned name is the same as the #wasm_frame_t itself.
+ */
 WASM_API_EXTERN const wasm_name_t *wasmtime_frame_func_name(const wasm_frame_t*);
+
+/**
+ * \brief Returns a human-readable name for this frame's module.
+ *
+ * This function will attempt to load a human-readable name for module this
+ * frame points to. This function may return `NULL`.
+ *
+ * The lifetime of the returned name is the same as the #wasm_frame_t itself.
+ */
 WASM_API_EXTERN const wasm_name_t *wasmtime_frame_module_name(const wasm_frame_t*);
 
-///////////////////////////////////////////////////////////////////////////////
+/**
-//
+ * \brief Call a WebAssembly function.
-// Extensions to the C API which augment existing functionality with extra
+ *
-// error reporting, safety, etc.
+ * This function is similar to #wasm_func_call, but with a few tweaks:
-
+ *
-// Similar to `wasm_func_call`, but with a few tweaks:
+ * * `args` and `results` have a size parameter saying how big the arrays are
-//
+ * * An error *and* a trap can be returned
-// * `args` and `results` have a size parameter saying how big the arrays are
+ * * Errors are returned if `args` have the wrong types, if the args/results
-// * An error *and* a trap can be returned
+ *   arrays have the wrong lengths, or if values come from the wrong store.
-// * Errors are returned if `args` have the wrong types, if the args/results
+ *
-//   arrays have the wrong lengths, or if values come from the wrong store.
+ * The are three possible return states from this function:
-//
+ *
-// The are three possible return states from this function:
+ * 1. The returned error is non-null. This means `results`
-//
+ *    wasn't written to and `trap` will have `NULL` written to it. This state
-// 1. The returned error is non-null. This means `results`
+ *    means that programmer error happened when calling the function (e.g. the
-//    wasn't written to and `trap` will have `NULL` written to it. This state
+ *    size of the args/results were wrong)
-//    means that programmer error happened when calling the function (e.g. the
+ * 2. The trap pointer is filled in. This means the returned error is `NULL` and
-//    size of the args/results were wrong)
+ *    `results` was not written to. This state means that the function was
-// 2. The trap pointer is filled in. This means the returned error is `NULL` and
+ *    executing but hit a wasm trap while executing.
-//    `results` was not written to. This state means that the function was
+ * 3. The error and trap returned are both `NULL` and `results` are written to.
-//    executing but hit a wasm trap while executing.
+ *    This means that the function call worked and the specified results were
-// 3. The error and trap returned are both `NULL` and `results` are written to.
+ *    produced.
-//    This means that the function call worked and the specified results were
+ *
-//    produced.
+ * The `trap` pointer cannot be `NULL`. The `args` and `results` pointers may be
-//
+ * `NULL` if the corresponding length is zero.
-// The `trap` pointer cannot be `NULL`. The `args` and `results` pointers may be
+ */
-// `NULL` if the corresponding length is zero.
 WASM_API_EXTERN own wasmtime_error_t *wasmtime_func_call(
     wasm_func_t *func,
     const wasm_val_t *args,
@@ -250,12 +661,19 @@ WASM_API_EXTERN own wasmtime_error_t *wasmtime_func_call(
     own wasm_trap_t **trap
 );
 
-// Similar to `wasm_global_new`, but with a few tweaks:
+/**
-//
+ * \brief Creates a new global value.
-// * An error is returned instead of `wasm_global_t`, which is taken as an
+ *
-//   out-parameter
+ * Similar to #wasm_global_new, but with a few tweaks:
-// * An error happens when the `type` specified does not match the type of the
+ *
-//   value `val`, or if it comes from a different store than `store`.
+ * * An error is returned instead of #wasm_global_t, which is taken as an
+ *   out-parameter
+ * * An error happens when the `type` specified does not match the type of the
+ *   value `val`, or if it comes from a different store than `store`.
+ *
+ * This function does not take ownership of any of its arguments but returned
+ * values are owned by the caller.
+ */
 WASM_API_EXTERN own wasmtime_error_t *wasmtime_global_new(
     wasm_store_t *store,
     const wasm_globaltype_t *type,
@@ -263,26 +681,38 @@ WASM_API_EXTERN own wasmtime_error_t *wasmtime_global_new(
     own wasm_global_t **ret
 );
 
-// Similar to `wasm_global_set`, but with an error that can be returned if the
+/**
-// specified value does not come from the same store as this global, if the
+ * \brief Sets a global to a new value.
-// global is immutable, or if the specified value has the wrong type.
+ *
+ * This function is the same as #wasm_global_set, except in the case of an error
+ * a #wasmtime_error_t is returned.
+ */
 WASM_API_EXTERN own wasmtime_error_t *wasmtime_global_set(
     wasm_global_t *global,
     const wasm_val_t *val
 );
 
-// Similar to `wasm_instance_new`, but with tweaks:
+/**
-//
+ * \brief Wasmtime-specific function to instantiate a module.
-// * An error message can be returned from this function.
+ *
-// * The number of imports specified is passed as an argument
+ * This function is similar to #wasm_instance_new, but with a few tweaks:
-// * The `trap` pointer is required to not be NULL.
+ *
-// * No `wasm_store_t` argument is required.
+ * * An error message can be returned from this function.
-//
+ * * The number of imports specified is passed as an argument
-// The states of return values from this function are similar to
+ * * The `trap` pointer is required to not be NULL.
-// `wasmtime_func_call` where an error can be returned meaning something like a
+ *
-// link error in this context. A trap can be returned (meaning no error or
+ * The states of return values from this function are similar to
-// instance is returned), or an instance can be returned (meaning no error or
+ * #wasmtime_func_call where an error can be returned meaning something like a
-// trap is returned).
+ * link error in this context. A trap can be returned (meaning no error or
+ * instance is returned), or an instance can be returned (meaning no error or
+ * trap is returned).
+ *
+ * This function does not take ownership of any of its arguments, but all return
+ * values are owned by the caller.
+ *
+ * See #wasm_instance_new for information about how to fill in the `imports`
+ * array.
+ */
 WASM_API_EXTERN own wasmtime_error_t *wasmtime_instance_new(
     wasm_store_t *store,
     const wasm_module_t *module,
@@ -292,40 +722,110 @@ WASM_API_EXTERN own wasmtime_error_t *wasmtime_instance_new(
     own wasm_trap_t **trap
 );
 
-// Similar to `wasm_module_new`, but an error is returned to return a
+/**
-// descriptive error message in case compilation fails.
+ * \brief Wasmtime-specific function to compile a module.
+ *
+ * This function will compile a WebAssembly binary into an owned #wasm_module_t.
+ * This performs the same as #wasm_module_new except that it returns a
+ * #wasmtime_error_t type to get richer error information.
+ *
+ * On success the returned #wasmtime_error_t is `NULL` and the `ret` pointer is
+ * filled in with a #wasm_module_t. On failure the #wasmtime_error_t is
+ * non-`NULL` and the `ret` pointer is unmodified.
+ *
+ * This function does not take ownership of any of its arguments, but the
+ * returned error and module are owned by the caller.
+ */
 WASM_API_EXTERN own wasmtime_error_t *wasmtime_module_new(
     wasm_store_t *store,
     const wasm_byte_vec_t *binary,
     own wasm_module_t **ret
 );
 
-// Similar to `wasm_module_validate`, but an error is returned to return a
+/**
-// descriptive error message in case compilation fails.
+ * \brief Wasmtime-specific function to validate a module.
+ *
+ * This function will validate the provided byte sequence to determine if it is
+ * a valid WebAssembly binary. This function performs the same as
+ * #wasm_module_validate except that it returns a #wasmtime_error_t which
+ * contains an error message if validation fails.
+ *
+ * This function does not take ownership of its arguments but the caller is
+ * expected to deallocate the returned error if it is non-`NULL`.
+ *
+ * If the binary validates then `NULL` is returned, otherwise the error returned
+ * describes why the binary did not validate.
+ */
 WASM_API_EXTERN own wasmtime_error_t *wasmtime_module_validate(
     wasm_store_t *store,
     const wasm_byte_vec_t *binary
 );
 
 
-// Similar to `wasm_table_*`, except these explicitly operate on funcref tables
+/**
-// and work with `wasm_func_t` values instead of `wasm_ref_t`.
+ * \brief Creates a new host-defined wasm table.
+ *
+ * This function is the same as #wasm_table_new except that it's specialized for
+ * funcref tables by taking a `wasm_func_t` initialization value. Additionally
+ * it returns errors via #wasmtime_error_t.
+ *
+ * This function does not take ownership of any of its parameters, but yields
+ * ownership of returned values (the table and error).
+ */
 WASM_API_EXTERN own wasmtime_error_t *wasmtime_funcref_table_new(
     wasm_store_t *store,
     const wasm_tabletype_t *element_ty,
     wasm_func_t *init,
     own wasm_table_t **table
 );
+
+/**
+ * \brief Gets a value in a table.
+ *
+ * This function is the same as #wasm_table_get except that it's specialized for
+ * funcref tables by returning a `wasm_func_t` value. Additionally a `bool`
+ * return value indicates whether the `index` provided was in bounds.
+ *
+ * This function does not take ownership of any of its parameters, but yields
+ * ownership of returned #wasm_func_t.
+ */
 WASM_API_EXTERN bool wasmtime_funcref_table_get(
     const wasm_table_t *table,
     wasm_table_size_t index,
     own wasm_func_t **func
 );
+
+/**
+ * \brief Sets a value in a table.
+ *
+ * This function is similar to #wasm_table_set, but has a few differences:
+ *
+ * * An error is returned through #wasmtime_error_t describing erroneous
+ *   situations.
+ * * The value being set is specialized to #wasm_func_t.
+ *
+ * This function does not take ownership of any of its parameters, but yields
+ * ownership of returned #wasmtime_error_t.
+ */
 WASM_API_EXTERN own wasmtime_error_t *wasmtime_funcref_table_set(
     wasm_table_t *table,
     wasm_table_size_t index,
     const wasm_func_t *value
 );
+
+/**
+ * \brief Grows a table.
+ *
+ * This function is similar to #wasm_table_grow, but has a few differences:
+ *
+ * * An error is returned through #wasmtime_error_t describing erroneous
+ *   situations.
+ * * The initialization value is specialized to #wasm_func_t.
+ * * The previous size of the table is returned through `prev_size`.
+ *
+ * This function does not take ownership of any of its parameters, but yields
+ * ownership of returned #wasmtime_error_t.
+ */
 WASM_API_EXTERN wasmtime_error_t *wasmtime_funcref_table_grow(
     wasm_table_t *table,
     wasm_table_size_t delta,