From d719b245c69627605de555b975afac12b39cf00d Mon Sep 17 00:00:00 2001 From: Xin Liu Date: Tue, 1 Aug 2023 14:32:29 +0800 Subject: [PATCH] [Doc] Update rustdoc (#44) * doc(rust-sys): update rustdoc Signed-off-by: Xin Liu * doc(rust-sdk): update rustdoc and `README` Signed-off-by: Xin Liu * ci(release-sdk): publish async API doc Signed-off-by: Xin Liu * chore(rust-sdk): format code in `async` Signed-off-by: Xin Liu --------- Signed-off-by: Xin Liu --- .github/workflows/release-wasmedge-sdk.yml | 14 ++++++++++++++ README.md | 4 ++-- crates/wasmedge-sys/src/executor.rs | 6 +++--- crates/wasmedge-sys/src/instance/module.rs | 2 +- src/async.rs | 20 +++++++++++++++++++- src/io.rs | 9 ++------- src/lib.rs | 2 +- src/plugin.rs | 2 ++ src/vm.rs | 4 ++-- src/wasi.rs | 2 +- 10 files changed, 47 insertions(+), 18 deletions(-) diff --git a/.github/workflows/release-wasmedge-sdk.yml b/.github/workflows/release-wasmedge-sdk.yml index 79c49edf3..c5d0f4313 100644 --- 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 index dd73fd2b2..53788130b 100644 --- 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 index 8c4074089..7274eda85 100644 --- 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 index fa6f935ba..b9c20734d 100644 --- 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 index e23cb944e..38b14f6bb 100644 --- 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>, envs: Option>, @@ -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 index 3adccd100..353296443 100644 --- 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 index a3e8f0504..8d0beadca 100644 --- 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 index dda5fc1da..9bcd8c7d9 100644 --- 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 index 59e85f494..8197b1f80 100644 --- 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 index cf13aebc5..2fe8b75c0 100644 --- 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;