Merge #1765

1765: doc(c-api) Update documentation. r=Hywan a=Hywan # Description This patch adds documentation to the `engine.rs` module. # Review - [ ] ~Add a short description of the the change to the CHANGELOG.md file~ not necessary Co-authored-by: Ivan Enderlin <[email protected]>
wasmerio · Oct 30, 2020 · 591691b · 591691b
2 parents 2d59b27 + ce525e7
commit 591691b
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 4 deletions.
diff --git a/lib/c-api/src/wasm_c_api/engine.rs b/lib/c-api/src/wasm_c_api/engine.rs
@@ -8,7 +8,10 @@ use wasmer_engine_native::Native;
 #[cfg(feature = "object-file")]
 use wasmer_engine_object_file::ObjectFile;
 
-/// this can be a wasmer-specific type with wasmer-specific functions for manipulating it
+/// Kind of compilers that can be used by the engines.
+///
+/// This is a Wasmer-specific type with Wasmer-specific functions for
+/// manipulating it.
 #[derive(Debug, Copy, Clone)]
 #[repr(C)]
 pub enum wasmer_compiler_t {
@@ -33,6 +36,10 @@ impl Default for wasmer_compiler_t {
     }
 }
 
+/// Kind of engines that can be used by the store.
+///
+/// This is a Wasmer-specific type with Wasmer-specific functions for
+/// manipulating it.
 #[derive(Debug, Copy, Clone)]
 #[repr(C)]
 #[allow(non_camel_case_types)]
@@ -58,21 +65,25 @@ impl Default for wasmer_engine_t {
     }
 }
 
+/// A configuration holds the compiler and the engine used by the store.
+///
 /// cbindgen:ignore
-/// this can be a wasmer-specific type with wasmer-specific functions for manipulating it
 #[derive(Debug, Default)]
 #[repr(C)]
 pub struct wasm_config_t {
     compiler: wasmer_compiler_t,
     engine: wasmer_engine_t,
 }
 
+/// Create a new Wasmer configuration.
+///
 /// cbindgen:ignore
 #[no_mangle]
 pub extern "C" fn wasm_config_new() -> Box<wasm_config_t> {
     Box::new(wasm_config_t::default())
 }
 
+/// Configure the compiler to use.
 #[no_mangle]
 pub extern "C" fn wasm_config_set_compiler(
     config: &mut wasm_config_t,
@@ -81,13 +92,17 @@ pub extern "C" fn wasm_config_set_compiler(
     config.compiler = compiler;
 }
 
+/// Configure the engine to use.
 #[no_mangle]
 pub extern "C" fn wasm_config_set_engine(config: &mut wasm_config_t, engine: wasmer_engine_t) {
     config.engine = engine;
 }
 
+/// An engine is used by the store to drive the compilation and the
+/// execution of a WebAssembly module.
+///
 /// cbindgen:ignore
-#[allow(non_camel_case_types)]
+#[repr(C)]
 pub struct wasm_engine_t {
     pub(crate) inner: Arc<dyn Engine + Send + Sync>,
 }
@@ -112,6 +127,7 @@ fn get_default_compiler_config() -> Box<dyn CompilerConfig> {
 
 cfg_if! {
     if #[cfg(all(feature = "jit", feature = "compiler"))] {
+        /// cbindgen:ignore
         #[no_mangle]
         pub extern "C" fn wasm_engine_new() -> Box<wasm_engine_t> {
             let compiler_config: Box<dyn CompilerConfig> = get_default_compiler_config();
@@ -121,13 +137,15 @@ cfg_if! {
     }
     else if #[cfg(feature = "jit")] {
         // Headless JIT
+        /// cbindgen:ignore
         #[no_mangle]
         pub extern "C" fn wasm_engine_new() -> Box<wasm_engine_t> {
             let engine: Arc<dyn Engine + Send + Sync> = Arc::new(JIT::headless().engine());
             Box::new(wasm_engine_t { inner: engine })
         }
     }
     else if #[cfg(all(feature = "native", feature = "compiler"))] {
+        /// cbindgen:ignore
         #[no_mangle]
         pub extern "C" fn wasm_engine_new() -> Box<wasm_engine_t> {
             let mut compiler_config: Box<dyn CompilerConfig> = get_default_compiler_config();
@@ -136,6 +154,7 @@ cfg_if! {
         }
     }
     else if #[cfg(feature = "native")] {
+        /// cbindgen:ignore
         #[no_mangle]
         pub extern "C" fn wasm_engine_new() -> Box<wasm_engine_t> {
             let engine: Arc<dyn Engine + Send + Sync> = Arc::new(Native::headless().engine());
@@ -145,13 +164,15 @@ cfg_if! {
     // There are currently no uses of the object-file engine + compiler from the C API.
     // So if we get here, we default to headless mode regardless of if `compiler` is enabled.
     else if #[cfg(feature = "object-file")] {
+        /// cbindgen:ignore
         #[no_mangle]
         pub extern "C" fn wasm_engine_new() -> Box<wasm_engine_t> {
             let engine: Arc<dyn Engine + Send + Sync> = Arc::new(ObjectFile::headless().engine());
             Box::new(wasm_engine_t { inner: engine })
         }
     }
     else {
+        /// cbindgen:ignore
         #[no_mangle]
         pub extern "C" fn wasm_engine_new() -> Box<wasm_engine_t> {
             unimplemented!("The JITEngine is not attached; You might want to recompile `wasmer_c_api` with `--feature jit`");

diff --git a/lib/c-api/wasmer_wasm.h b/lib/c-api/wasmer_wasm.h
@@ -53,14 +53,23 @@
 #include "wasm.h"
 
 /**
- * this can be a wasmer-specific type with wasmer-specific functions for manipulating it
+ * Kind of compilers that can be used by the engines.
+ *
+ * This is a Wasmer-specific type with Wasmer-specific functions for
+ * manipulating it.
  */
 typedef enum {
   CRANELIFT = 0,
   LLVM = 1,
   SINGLEPASS = 2,
 } wasmer_compiler_t;
 
+/**
+ * Kind of engines that can be used by the store.
+ *
+ * This is a Wasmer-specific type with Wasmer-specific functions for
+ * manipulating it.
+ */
 typedef enum {
   JIT = 0,
   NATIVE = 1,
@@ -156,8 +165,14 @@ wasm_func_t *wasi_get_start_function(wasm_instance_t *instance);
 wasi_version_t wasi_get_wasi_version(const wasm_module_t *module);
 #endif
 
+/**
+ * Configure the compiler to use.
+ */
 void wasm_config_set_compiler(wasm_config_t *config, wasmer_compiler_t compiler);
 
+/**
+ * Configure the engine to use.
+ */
 void wasm_config_set_engine(wasm_config_t *config, wasmer_engine_t engine);
 
 void wasm_module_name(const wasm_module_t *module, wasm_name_t *out);