[Doc] Update rustdoc (#44)

* doc(rust-sys): update rustdoc Signed-off-by: Xin Liu <[email protected]> * doc(rust-sdk): update rustdoc and `README` Signed-off-by: Xin Liu <[email protected]> * ci(release-sdk): publish async API doc Signed-off-by: Xin Liu <[email protected]> * chore(rust-sdk): format code in `async` Signed-off-by: Xin Liu <[email protected]> --------- Signed-off-by: Xin Liu <[email protected]>
WasmEdge · Aug 1, 2023 · d719b24 · d719b24
1 parent 8507919
commit d719b24
Show file tree

Hide file tree

Showing 10 changed files with 47 additions and 18 deletions.
diff --git a/.github/workflows/release-wasmedge-sdk.yml b/.github/workflows/release-wasmedge-sdk.yml
@@ -76,3 +76,17 @@ jobs:
           publish_branch: gh-pages
           publish_dir: wasmedge-rust-sdk/target/doc
           force_orphan: true
+
+      - name: Build Async API document
+        working-directory: wasmedge-rust-sdk
+        run: |
+          cargo doc -p wasmedge-sdk --workspace --no-deps --features aot,async,wasi_crypto,wasi_nn,wasmedge_process,ffi --target-dir=./target/async-wasmedge
+
+      - name: Deploy Async API document
+        if: github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: wasmedge-rust-sdk/target/async-wasmedge/doc
+          force_orphan: true
diff --git a/README.md b/README.md
@@ -4,15 +4,15 @@ WasmEdge Rust SDK provides idiomatic [Rust](https://www.rust-lang.org/) language
 
 **Notice:** This project is still under active development and not guaranteed to have a stable API.
 
-- [Documentation](https://wasmedge.org/docs/)
 - [WasmEdge website](https://wasmedge.org/)
+- [WasmEdge Docs](https://wasmedge.org/docs/)
 - [WasmEdge GitHub Page](https://github.com/WasmEdge/WasmEdge)
 - [WasmEdge Rust SDK GitHub Page](https://github.com/WasmEdge/wasmedge-rust-sdk)
 - [WasmEdge Rust SDK Examples](https://github.com/second-state/wasmedge-rustsdk-examples)
 
 ## Get Started
 
-Since this crate depends on the WasmEdge C API, it needs to be installed in your system first. Please refer to [WasmEdge Installation and Uninstallation](https://wasmedge.org/book/en/quick_start/install.html) to install the WasmEdge library. The versioning table below shows the version of the WasmEdge library required by each version of the `wasmedge-sdk` crate.
+Since this crate depends on the WasmEdge C API, it needs to be installed in your system first. Please refer to [Install and uninstall WasmEdge](https://wasmedge.org/docs/start/install) to install the WasmEdge library. The versioning table below shows the version of the WasmEdge library required by each version of the `wasmedge-sdk` crate.
 
   | wasmedge-sdk  | WasmEdge lib  | wasmedge-sys  | wasmedge-types| wasmedge-macro| async-wasi|
   | :-----------: | :-----------: | :-----------: | :-----------: | :-----------: | :-------: |

diff --git a/crates/wasmedge-sys/src/executor.rs b/crates/wasmedge-sys/src/executor.rs
@@ -61,7 +61,7 @@ impl Executor {
     ///
     /// # Arguments
     ///
-    /// * `store` - The target [store](crate::Store), into which the given [import object](crate::ImportObject) is registered.
+    /// * `store` - The target [store](crate::Store), into which the given [wasi instance] is registered.
     ///
     /// * `instance` - The [WASI instance](crate::WasiInstance) to be registered.
     ///
@@ -99,7 +99,7 @@ impl Executor {
     ///
     /// # Arguments
     ///
-    /// * `store` - The target [store](crate::Store), into which the given [import object](crate::ImportObject) is registered.
+    /// * `store` - The target [store](crate::Store), into which the given [import module](crate::ImportModule) is registered.
     ///
     /// * `import` - The WasmEdge [import module](crate::ImportModule) to be registered.
     ///
@@ -166,7 +166,7 @@ impl Executor {
 
     /// Registers and instantiates a WasmEdge [module](crate::Module) into a [store](crate::Store) as an anonymous module.
     ///
-    /// Notice that when a new module is instantiated into the [store](crate::Store), the old instantiated module is removed; in addition, ensure that the [imports](crate::ImportObject) the module depends are already registered into the [store](crate::Store).
+    /// Notice that when a new module is instantiated into the [store](crate::Store), the old instantiated module is removed; in addition, ensure that the [imports](crate::ImportModule) the module depends on are already registered into the [store](crate::Store).
     ///
     ///
     /// # Arguments

diff --git a/crates/wasmedge-sys/src/instance/module.rs b/crates/wasmedge-sys/src/instance/module.rs
@@ -718,7 +718,7 @@ impl WasiModule {
     }
 }
 
-/// The object to be registered via the the [Executor::register_import_object](crate::Executor::register_import_object) function is required to implement this trait.
+/// The module to be registered via the the [Executor::register_import_module](crate::Executor::register_import_module) function is required to implement this trait.
 pub trait AsImport {
     /// Returns the name of the module instance.
     fn name(&self) -> &str;

diff --git a/src/async.rs b/src/async.rs
@@ -1,20 +1,35 @@
+//! Defines the types used in the `async` scenarios.
+
 /// The state of an asynchronous task.
 pub type AsyncState = wasmedge_sys::r#async::fiber::AsyncState;
 
-/// Represents a wasi module instance.
+/// Represents a wasi module instance for the `async` scenarios.
 #[derive(Debug, Clone)]
 pub struct WasiInstance(pub(crate) wasmedge_sys::r#async::AsyncWasiModule);
 impl WasiInstance {
+    /// Returns the WASI exit code.
+    ///
+    /// The WASI exit code can be accessed after running the "_start" function of a `wasm32-wasi` program.
     pub fn exit_code(&self) -> u32 {
         self.0.exit_code()
     }
 }
 
+/// Represents a wasi context for the `async` scenarios.
 #[derive(Debug)]
 pub struct WasiContext {
     pub(crate) inner: async_wasi::WasiCtx,
 }
 impl WasiContext {
+    /// Creates a wasi context with the specified argumentes, environment variables, and preopened directories.
+    ///
+    /// # Arguments
+    ///
+    /// * `args` - The commandline arguments. The first argument is the program name.
+    ///
+    /// * `envs` - The environment variables to use.
+    ///
+    /// * `preopens` - The directories to pre-open. The first element of the pair is the host directory, while the second is the guest directory.
     pub fn new(
         args: Option<Vec<&str>>,
         envs: Option<Vec<(&str, &str)>>,
@@ -40,6 +55,9 @@ impl WasiContext {
         Self { inner }
     }
 
+    /// Returns the WASI exit code.
+    ///
+    /// The WASI exit code can be accessed after running the "_start" function of a `wasm32-wasi` program.
     pub fn exit_code(&self) -> u32 {
         self.inner.exit_code
     }

diff --git a/src/io.rs b/src/io.rs
@@ -291,14 +291,9 @@ impl WasmVal for ExternRef {
     }
 }
 
-/// Used to pass arguments to the following methods:
-/// - [Func::run](crate::Func::run)
-/// - [FuncRef::run](crate::FuncRef::run)
-/// - [Executor::run_func](crate::Executor::run_func)
-/// - [Executor::run_func_ref](crate::Executor::run_func_ref)
-/// - [Vm::run_func](crate::Vm::run_func)
+/// Generates arguments of [WasmValue](crate::WasmValue) types.
 ///
-/// Notice that to use the macro, it is required to use `WasmVal` trait. If the version of rust used is less than v1.63, please place `#![feature(explicit_generic_args_with_impl_trait)]` on the root of the program.
+/// Notice that to use the macro, it is required to use `WasmVal` trait.
 #[macro_export]
 macro_rules! params {
     ( $( $x:expr ),* ) => {

diff --git a/src/lib.rs b/src/lib.rs
@@ -12,8 +12,8 @@
 //!
 //! **Notice:** This project is still under active development and not guaranteed to have a stable API.
 //!
-//! - [Documentation](https://wasmedge.org/docs/)
 //! - [WasmEdge website](https://wasmedge.org/)
+//! - [WasmEdge Docs](https://wasmedge.org/docs/)
 //! - [WasmEdge GitHub Page](https://github.com/WasmEdge/WasmEdge)
 //! - [WasmEdge Rust SDK GitHub Page](https://github.com/WasmEdge/wasmedge-rust-sdk)
 //! - [WasmEdge Rust SDK Examples](https://github.com/second-state/wasmedge-rustsdk-examples)

diff --git a/src/plugin.rs b/src/plugin.rs
@@ -5,6 +5,8 @@ use crate::{
     Memory, Table, WasmEdgeResult, WasmValue,
 };
 use wasmedge_sys::{self as sys, AsImport};
+
+/// Defines low-level types used in Plugin development.
 pub mod ffi {
     pub use wasmedge_sys::ffi::{
         WasmEdge_ModuleDescriptor, WasmEdge_ModuleInstanceContext, WasmEdge_PluginDescriptor,

diff --git a/src/vm.rs b/src/vm.rs
@@ -755,7 +755,7 @@ impl Vm {
         &mut self.store
     }
 
-    /// Returns a reference to the [wasi module instance](crate::wasi::WasiInstance) from this vm.
+    /// Returns a reference to the [wasi module instance] from this vm.
     ///
     /// To retrieve  the [wasi module instance], a [config](crate::config::Config) with the enabled [wasi](crate::config::HostRegistrationConfigOptions::wasi) option should be given when create this vm.
     ///
@@ -766,7 +766,7 @@ impl Vm {
         }
     }
 
-    /// Returns a mutable reference to the [wasi module instance](crate::wasi::WasiInstance) from this vm.
+    /// Returns a mutable reference to the [wasi module instance] from this vm.
     ///
     /// To retrieve the [wasi module instance], a [config](crate::config::Config) with the enabled [wasi](crate::config::HostRegistrationConfigOptions::wasi) option should be given when create this vm.
     ///

diff --git a/src/wasi.rs b/src/wasi.rs
@@ -1,4 +1,4 @@
-//! Defines wasi module instance types, including WasiInstance, WasiNnInstance, wasi-crypto instances.
+//! Defines wasi module instance.
 
 use crate::WasmEdgeResult;