Merge #439

439: doc(runtime-c-api) Add short module descriptions - cont r=syrusakbary a=syrusakbary

This PR supersedes #313 

Co-authored-by: Ivan Enderlin <ivan.enderlin@hoa-project.net>
Co-authored-by: Syrus <me@syrusakbary.com>

lib/runtime-c-api/src/error.rs

@@ -1,4 +1,4 @@
-//! Errors.
+//! Read runtime errors.
 
 use libc::{c_char, c_int};
 use std::cell::RefCell;

lib/runtime-c-api/src/export.rs

@@ -1,4 +1,5 @@
-//! Wasm exports.
+//! Create, read, destroy export definitions (function, global, memory
+//! and table) on an instance.
 
 use crate::{
     error::{update_last_error, CApiError},

lib/runtime-c-api/src/global.rs

@@ -1,4 +1,4 @@
-//! Wasm global.
+//! Create, set, get and destroy global variables of an instance.
 
 use crate::value::{wasmer_value_t, wasmer_value_tag};
 use wasmer_runtime::Global;

lib/runtime-c-api/src/import.rs

@@ -1,4 +1,5 @@
-//! Wasm imports.
+//! Create, read, destroy import definitions (function, global, memory
+//! and table) on an instance.
 
 use crate::{
     error::{update_last_error, CApiError},

lib/runtime-c-api/src/instance.rs

@@ -1,4 +1,4 @@
-//! Wasm instance.
+//! Instantiate a module, call functions, and read exports.
 
 use crate::{
     error::{update_last_error, CApiError},

lib/runtime-c-api/src/lib.rs

@@ -1,3 +1,85 @@
+//! # Wasmer Runtime C API
+//!
+//! Wasmer is a standalone JIT WebAssembly runtime, aiming to be fully
+//! compatible with Emscripten, Rust and Go. [Learn
+//! more](https://github.com/wasmerio/wasmer).
+//!
+//! This crate exposes a C and C++ API for the Wasmer runtime.
+//!
+//! # Usage
+//!
+//! The C and C++ header files can be found in the source tree of this
+//! crate, respectively [`wasmer.h`][wasmer_h] and
+//! [`wasmer.hh`][wasmer_hh]. They are automatically generated, and always
+//! up-to-date in this repository.
+//!
+//! Here is a simple example to use the C API:
+//!
+//! ```c
+//! #include <stdio.h>
+//! #include "wasmer.h"
+//! #include <assert.h>
+//! #include <stdint.h>
+//!
+//! int main()
+//! {
+//!     // Read the Wasm file bytes.
+//!     FILE *file = fopen("sum.wasm", "r");
+//!     fseek(file, 0, SEEK_END);
+//!     long len = ftell(file);
+//!     uint8_t *bytes = malloc(len);
+//!     fseek(file, 0, SEEK_SET);
+//!     fread(bytes, 1, len, file);
+//!     fclose(file);
+//!
+//!     // Prepare the imports.
+//!     wasmer_import_t imports[] = {};
+//!
+//!     // Instantiate!
+//!     wasmer_instance_t *instance = NULL;
+//!     wasmer_result_t instantiation_result = wasmer_instantiate(&instance, bytes, len, imports, 0);
+//!
+//!     assert(instantiation_result == WASMER_OK);
+//!
+//!     // Let's call a function.
+//!     // Start by preparing the arguments.
+//!
+//!     // Value of argument #1 is `7i32`.
+//!     wasmer_value_t argument_one;
+//!     argument_one.tag = WASM_I32;
+//!     argument_one.value.I32 = 7;
+//!
+//!     // Value of argument #2 is `8i32`.
+//!     wasmer_value_t argument_two;
+//!     argument_two.tag = WASM_I32;
+//!     argument_two.value.I32 = 8;
+//!
+//!     // Prepare the arguments.
+//!     wasmer_value_t arguments[] = {argument_one, argument_two};
+//!
+//!     // Prepare the return value.
+//!     wasmer_value_t result_one;
+//!     wasmer_value_t results[] = {result_one};
+//!
+//!     // Call the `sum` function with the prepared arguments and the return value.
+//!     wasmer_result_t call_result = wasmer_instance_call(instance, "sum", arguments, 2, results, 1);
+//!
+//!     // Let's display the result.
+//!     printf("Call result:  %d\n", call_result);
+//!     printf("Result: %d\n", results[0].value.I32);
+//!
+//!     // `sum(7, 8) == 15`.
+//!     assert(results[0].value.I32 == 15);
+//!     assert(call_result == WASMER_OK);
+//!
+//!     wasmer_instance_destroy(instance);
+//!
+//!     return 0;
+//! }
+//! ```
+//!
+//! [wasmer_h]: ./wasmer.h
+//! [wasmer_hh]: ./wasmer.hh
 #![deny(unused_imports, unused_variables, unused_unsafe, unreachable_patterns)]
 
 extern crate wasmer_runtime;

lib/runtime-c-api/src/memory.rs

@@ -1,4 +1,4 @@
-//! Wasm memory.o
+//! Create, read, write, grow, destroy memory of an instance.
 
 use crate::{error::update_last_error, wasmer_limits_t, wasmer_result_t};
 use libc::{uint32_t, uint8_t};

lib/runtime-c-api/src/module.rs

@@ -1,4 +1,4 @@
-//! Wasm module.
+//! Compile, validate, instantiate, serialize, and destroy modules.
 
 use crate::{
     error::{update_last_error, CApiError},

lib/runtime-c-api/src/table.rs

@@ -1,4 +1,4 @@
-//! Wasm tables.
+//! Create, grow, destroy tables of an instance.
 
 use crate::{error::update_last_error, wasmer_limits_t, wasmer_result_t};
 use libc::uint32_t;

lib/runtime-c-api/src/value.rs

@@ -1,4 +1,4 @@
-//! Wasm values.
+//! Create and map Rust to WebAssembly values.
 
 use libc::{int32_t, int64_t};
 use wasmer_runtime::Value;