Merge #2083

2083: doc(c-api) Remove inline documentation in `wasmer_wasm.h`, clarification about stability… r=Hywan a=Hywan # Description As suggested in #2053 (comment), this PR removes the automatically generated documentation when building `wasmer_wasm.h`. It also clarifies our position regarding stability, and add a section about the documentation. This PR takes also the opportunity to mark `wasi_env_set_(instance|memory)` as deprecated functions. # Review - [x] Add a short description of the the change to the CHANGELOG.md file Co-authored-by: Ivan Enderlin <[email protected]>
wasmerio · Feb 2, 2021 · c4c7b2b · c4c7b2b
2 parents 3af8932 + b2bc62d
commit c4c7b2b
Show file tree

Hide file tree

Showing 4 changed files with 99 additions and 432 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,7 @@
 - [#2054](https://github.com/wasmerio/wasmer/pull/2054) Add `wasm_config_delete` to the Wasm C API.
 
 ### Changed
+- [#2083](https://github.com/wasmerio/wasmer/pull/2083) Mark `wasi_env_set_(instance|memory)` as deprecated. You may simply remove them with no side-effect.
 - [#2056](https://github.com/wasmerio/wasmer/pull/2056) Change back to depend on the `enumset` crate instead of `wasmer_enumset`
 
 ### Fixed

diff --git a/lib/c-api/build.rs b/lib/c-api/build.rs
@@ -89,8 +89,41 @@ fn build_wasm_c_api_headers(crate_dir: &str, out_dir: &str) {
     out_header_file.push("wasmer_wasm");
 
     let mut pre_header = format!(
-        r#"// The Wasmer C/C++ header file compatible with the `wasm-c-api` standard API.
-// This file is generated by lib/c-api/build.rs.
+        r#"// The Wasmer C/C++ header file compatible with the [`wasm-c-api`]
+// standard API, as `wasm.h` (included here).
+//
+// This file is automatically generated by `lib/c-api/build.rs` of the
+// [`wasmer-c-api`] Rust crate.
+//
+// # Stability
+//
+// The [`wasm-c-api`] standard API is a _living_ standard. There is no
+// commitment for stability yet. We (Wasmer) will try our best to keep
+// backward compatibility as much as possible. Nonetheless, some
+// necessary API aren't yet standardized, and as such, we provide a
+// custom API, e.g. `wasi_*` types and functions.
+//
+// The documentation makes it clear whether a function is unstable.
+// 
+// When a type or a function will be deprecated, it will be marked as
+// such with the appropriated compiler warning, and will be removed at
+// the next release round.
+//
+// # Documentation
+//
+// At the time of writing, the [`wasm-c-api`] standard has no
+// documentation. This file also does not include inline
+// documentation. However, we have made (and we continue to make) an
+// important effort to document everything. [See the documentation
+// online][documentation]. Please refer to this page for the real
+// canonical documentation. It also contains numerous examples.
+//
+// To generate the documentation locally, run `cargo doc --open` from
+// within the [`wasmer-c-api`] Rust crate.
+//
+// [`wasm-c-api`]: https://github.com/WebAssembly/wasm-c-api
+// [`wasmer-c-api`]: https://github.com/wasmerio/wasmer/tree/master/lib/c-api
+// [documentation]: https://wasmerio.github.io/wasmer/crates/wasmer_c_api/
 
 #if !defined(WASMER_WASM_H_PRELUDE)
 
@@ -184,10 +217,12 @@ fn build_wasmer_c_api_headers(crate_dir: &str, out_dir: &str) {
         out_header_file.set_extension("h");
 
         // Build and generate the header file.
-        exclude_items_from_wasm_c_api(new_builder(Language::C, crate_dir, guard, &pre_header))
-            .generate()
-            .expect("Unable to generate C bindings")
-            .write_to_file(out_header_file.as_path());
+        exclude_items_from_wasm_c_api(
+            new_builder(Language::C, crate_dir, guard, &pre_header).with_documentation(true),
+        )
+        .generate()
+        .expect("Unable to generate C bindings")
+        .write_to_file(out_header_file.as_path());
 
         // Copy the generated bindings from `OUT_DIR` to
         // `CARGO_MANIFEST_DIR`.
@@ -203,10 +238,12 @@ fn build_wasmer_c_api_headers(crate_dir: &str, out_dir: &str) {
         out_header_file.set_extension("hh");
 
         // Build and generate the header file.
-        exclude_items_from_wasm_c_api(new_builder(Language::Cxx, crate_dir, guard, &pre_header))
-            .generate()
-            .expect("Unable to generate C++ bindings")
-            .write_to_file(out_header_file.as_path());
+        exclude_items_from_wasm_c_api(
+            new_builder(Language::Cxx, crate_dir, guard, &pre_header).with_documentation(true),
+        )
+        .generate()
+        .expect("Unable to generate C++ bindings")
+        .write_to_file(out_header_file.as_path());
 
         // Copy the generated bindings from `OUT_DIR` to
         // `CARGO_MANIFEST_DIR`.
@@ -247,7 +284,7 @@ fn new_builder(language: Language, crate_dir: &str, include_guard: &str, header:
         .with_crate(crate_dir)
         .with_include_guard(include_guard)
         .with_header(header)
-        .with_documentation(true)
+        .with_documentation(false)
         .with_define("target_family", "windows", "_WIN32")
         .with_define("target_arch", "x86_64", "ARCH_X86_64")
         .with_define("feature", "jit", JIT_FEATURE_AS_C_DEFINE)

diff --git a/lib/c-api/src/wasm_c_api/wasi/mod.rs b/lib/c-api/src/wasm_c_api/wasi/mod.rs
@@ -199,30 +199,22 @@ pub extern "C" fn wasi_env_delete(_state: Option<Box<wasi_env_t>>) {}
 
 /// This function is deprecated. You may safely remove all calls to it and everything
 /// will continue to work.
-// Dead code: deprecate or remove
-#[allow(unused_variables)]
+///
+/// cbindgen:prefix=DEPRECATED("This function is no longer necessary. You may safely remove all calls to it and everything will continue to work.")
 #[no_mangle]
-pub extern "C" fn wasi_env_set_instance(env: &mut wasi_env_t, instance: &wasm_instance_t) -> bool {
-    /*
-    let memory = if let Ok(memory) = instance.inner.exports.get_memory("memory") {
-        memory
-    } else {
-        return false;
-    };
-    env.inner.set_memory(memory.clone());
-    */
-
+pub extern "C" fn wasi_env_set_instance(
+    _env: &mut wasi_env_t,
+    _instance: &wasm_instance_t,
+) -> bool {
     true
 }
 
 /// This function is deprecated. You may safely remove all calls to it and everything
 /// will continue to work.
-// Dead code: deprecate or remove
-#[allow(unused_variables)]
+///
+/// cbindgen:prefix=DEPRECATED("This function is no longer necessary. You may safely remove all calls to it and everything will continue to work.")
 #[no_mangle]
-pub extern "C" fn wasi_env_set_memory(env: &mut wasi_env_t, memory: &wasm_memory_t) {
-    //env.inner.set_memory(memory.inner.clone());
-}
+pub extern "C" fn wasi_env_set_memory(_env: &mut wasi_env_t, _memory: &wasm_memory_t) {}
 
 #[no_mangle]
 pub unsafe extern "C" fn wasi_env_read_stdout(