From b2564432d3dc76c0d3cdee6146ad6ebcff51a76e Mon Sep 17 00:00:00 2001
From: Ivan Enderlin <ivan@mnt.io>
Date: Mon, 14 Dec 2020 15:58:24 +0100
Subject: [PATCH] test+doc(c-api) Improve the documentation and test of the
 `module` module.

---
 lib/c-api/src/wasm_c_api/mod.rs    | 44 ++++++++++++++++++++++++--
 lib/c-api/src/wasm_c_api/module.rs | 50 +++++-------------------------
 2 files changed, 50 insertions(+), 44 deletions(-)

diff --git a/lib/c-api/src/wasm_c_api/mod.rs b/lib/c-api/src/wasm_c_api/mod.rs
index 8b918d31d..490291724 100644
--- a/lib/c-api/src/wasm_c_api/mod.rs
+++ b/lib/c-api/src/wasm_c_api/mod.rs
@@ -24,7 +24,7 @@
 #[macro_use]
 pub mod macros;
 
-/// The engine drives the compilation and the runtime.
+/// An engine drives the compilation and the runtime.
 ///
 /// Entry points: A default engine is created with
 /// [`wasm_engine_new`][engine::wasm_engine_new] and freed with
@@ -131,7 +131,47 @@ pub mod instance;
 /// already been compiled and can be instantiated multiple times.
 ///
 /// Entry points: A WebAssembly module is created with
-/// `wasm_module_new` and freed with `wasm_module_delete`.
+/// [`wasm_module_new`][module::wasm_module_new] and freed with
+/// [`wasm_module_delete`][module::wasm_module_delete].
+///
+/// # Example
+///
+/// ```rust
+/// # use inline_c::assert_c;
+/// # fn main() {
+/// #    (assert_c! {
+/// # #include "tests/wasmer_wasm.h"
+/// #
+/// int main() {
+///     // Create the engine and the store.
+///     wasm_engine_t* engine = wasm_engine_new();
+///     wasm_store_t* store = wasm_store_new(engine);
+///
+///     // Create a WebAssembly module from a WAT definition.
+///     wasm_byte_vec_t wat;
+///     wasmer_byte_vec_new_from_string(&wat, "(module)");
+///     wasm_byte_vec_t wasm;
+///     wat2wasm(&wat, &wasm);
+///    
+///     // Create the module.
+///     wasm_module_t* module = wasm_module_new(store, &wasm);
+///
+///     // It works!
+///     assert(module);
+///    
+///     // Free everything.
+///     wasm_byte_vec_delete(&wasm);
+///     wasm_byte_vec_delete(&wat);
+///     wasm_module_delete(module);
+///     wasm_store_delete(store);
+///     wasm_engine_delete(engine);
+///
+///     return 0;
+/// }
+/// #    })
+/// #    .success();
+/// # }
+/// ```
 ///
 /// cbindgen:ignore
 pub mod module;
diff --git a/lib/c-api/src/wasm_c_api/module.rs b/lib/c-api/src/wasm_c_api/module.rs
index feddc94f4..49f8a0009 100644
--- a/lib/c-api/src/wasm_c_api/module.rs
+++ b/lib/c-api/src/wasm_c_api/module.rs
@@ -27,42 +27,7 @@ pub struct wasm_module_t {
 ///
 /// # Example
 ///
-/// ```rust
-/// # use inline_c::assert_c;
-/// # fn main() {
-/// #    (assert_c! {
-/// # #include "tests/wasmer_wasm.h"
-/// #
-/// int main() {
-///     // Create the engine and the store.
-///     wasm_engine_t* engine = wasm_engine_new();
-///     wasm_store_t* store = wasm_store_new(engine);
-///
-///     // Create a WebAssembly module from a WAT definition.
-///     wasm_byte_vec_t wat;
-///     wasmer_byte_vec_new_from_string(&wat, "(module)");
-///     wasm_byte_vec_t wasm;
-///     wat2wasm(&wat, &wasm);
-///    
-///     // Create the module.
-///     wasm_module_t* module = wasm_module_new(store, &wasm);
-
-///     // It works!
-///     assert(module);
-///    
-///     // Free everything.
-///     wasm_byte_vec_delete(&wasm);
-///     wasm_byte_vec_delete(&wat);
-///     wasm_module_delete(module);
-///     wasm_store_delete(store);
-///     wasm_engine_delete(engine);
-///
-///     return 0;
-/// }
-/// #    })
-/// #    .success();
-/// # }
-/// ```
+/// See the module's documentation.
 #[no_mangle]
 pub unsafe extern "C" fn wasm_module_new(
     store: Option<&wasm_store_t>,
@@ -83,15 +48,15 @@ pub unsafe extern "C" fn wasm_module_new(
 ///
 /// # Example
 ///
-/// See `wasm_module_new`.
+/// See [`wasm_module_new`].
 #[no_mangle]
 pub unsafe extern "C" fn wasm_module_delete(_module: Option<Box<wasm_module_t>>) {}
 
 /// Validates a new WebAssembly module given the configuration
-/// in the `wasm_store_t`.
+/// in the [store][super::store].
 ///
 /// This validation is normally pretty fast and checks the enabled
-/// WebAssembly features in the store engine (`wasm_engine_t`) to
+/// WebAssembly features in the [store engine][super::engine] to
 /// assure deterministic validation of the module.
 ///
 /// # Example
@@ -530,12 +495,13 @@ pub unsafe extern "C" fn wasm_module_deserialize(
     ))))
 }
 
-/// Serializes a module into a binary representation that the engine
-/// (`wasm_engine_t`) can later process via `wasm_module_deserialize`.
+/// Serializes a module into a binary representation that the
+/// [engine][super::engine] can later process via
+/// [`wasm_module_deserialize`].
 ///
 /// # Example
 ///
-/// See `wasm_module_deserialize`.
+/// See [`wasm_module_deserialize`].
 #[no_mangle]
 pub unsafe extern "C" fn wasm_module_serialize(
     module: &wasm_module_t,