From c20261fe57965de0d8b443c133491459d09affe3 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Mon, 14 Dec 2020 15:14:54 +0100 Subject: [PATCH] doc(c-api) Improve the crate's documentation. --- lib/c-api/src/lib.rs | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/lib/c-api/src/lib.rs b/lib/c-api/src/lib.rs index 28946169b..11432f3a2 100644 --- a/lib/c-api/src/lib.rs +++ b/lib/c-api/src/lib.rs @@ -1,21 +1,29 @@ //! Wasmer C API. //! //! [Wasmer](https://github.com/wasmerio/wasmer) is the leading -//! WebAssembly runtime. This crate exposes the C and C++ bindings. +//! WebAssembly runtime. Wasmer is written in Rust; this crate +//! exposes its C and C++ bindings. //! -//! This crate provides 2 API: +//! This crate provides 2 different API: //! -//! * `deprecated`, which is the old one, and is represented by the -//! `wasmer.h` and the `wasmer.hh` C header files, -//! * `wasm_c_api`, which is the new, standard C API, and is -//! represented by the `wasmer_wasm.h` C header file. +//! 1. [`deprecated`], which is the old one, and is represented by the +//! `wasmer.h` and the `wasmer.hh` C and C++ header files, +//! 2. [`wasm_c_api`], which is the new standard C API, and is +//! represented by the `wasmer_wasm.h` C header file. //! -//! The `wasm_c_api` follows the [official WebAssembly C and C++ -//! API](https://github.com/WebAssembly/wasm-c-api). It provides -//! however some extensions, like the `wasi_*` types and functions, -//! which aren't yet defined by the standard. The `wasmer_wasm.h` -//! header file already depends on the `wasm.h` file. A copy lands in -//! this repository for the sake of simplicity. +//! The `wasm_c_api` follows the [official WebAssembly C +//! API](https://github.com/WebAssembly/wasm-c-api). This standard can +//! be characterized as a _living standard_. The API is not yet +//! stable, even though it shows maturity over time. It is described +//! by the `wasm.h` C header file. However, the `wasm_c_api` API +//! provides some extensions, like the `wasi_*` or `wasmer_*` types +//! and functions, which aren't yet defined by the standard. The +//! `wasmer_wasm.h` header file already depends on the `wasm.h` +//! file. A copy lands in this repository for the sake of simplicity. +//! +//! It is recommended to use the `wasm_c_api` API, despites it is not +//! yet officially stabilized, over the `deprecated` API, which is +//! more stable but less powerful and in a maintainance state. #![doc(html_favicon_url = "https://wasmer.io/static/icons/favicon.ico")] #![doc(html_logo_url = "https://github.com/wasmerio.png?size=200")]