Expand some docs on wasmtime-wasi (#11598)

Add public docs for APIs added in #11593 and additionally internalize
some crate fields to avoid exposing too many internal implementation
details.

Author: alexcrichton

crates/wasi/src/cli.rs

@@ -20,6 +20,44 @@ pub use self::locked_async::{AsyncStdinStream, AsyncStdoutStream};
 #[doc(no_inline)]
 pub use tokio::io::{Stderr, Stdin, Stdout, stderr, stdin, stdout};
 
+/// A helper struct which implements [`HasData`] for the `wasi:cli` APIs.
+///
+/// This can be useful when directly calling `add_to_linker` functions directly,
+/// such as [`wasmtime_wasi::p2::bindings::cli::environment::add_to_linker`] as
+/// the `D` type parameter. See [`HasData`] for more information about the type
+/// parameter's purpose.
+///
+/// When using this type you can skip the [`WasiCliView`] trait, for
+/// example.
+///
+/// # Examples
+///
+/// ```
+/// use wasmtime::component::{Linker, ResourceTable};
+/// use wasmtime::{Engine, Result, Config};
+/// use wasmtime_wasi::cli::*;
+///
+/// struct MyStoreState {
+///     table: ResourceTable,
+///     cli: WasiCliCtx,
+/// }
+///
+/// fn main() -> Result<()> {
+///     let mut config = Config::new();
+///     config.async_support(true);
+///     let engine = Engine::new(&config)?;
+///     let mut linker = Linker::new(&engine);
+///
+///     wasmtime_wasi::p2::bindings::cli::environment::add_to_linker::<MyStoreState, WasiCli>(
+///         &mut linker,
+///         |state| WasiCliCtxView {
+///             table: &mut state.table,
+///             ctx: &mut state.cli,
+///         },
+///     )?;
+///     Ok(())
+/// }
+/// ```
 pub struct WasiCli;
 
 impl HasData for WasiCli {

crates/wasi/src/clocks.rs

@@ -3,15 +3,53 @@ use cap_std::{AmbientAuthority, ambient_authority};
 use cap_time_ext::{MonotonicClockExt as _, SystemClockExt as _};
 use wasmtime::component::{HasData, ResourceTable};
 
+/// A helper struct which implements [`HasData`] for the `wasi:clocks` APIs.
+///
+/// This can be useful when directly calling `add_to_linker` functions directly,
+/// such as [`wasmtime_wasi::p2::bindings::clocks::monotonic_clock::add_to_linker`] as
+/// the `D` type parameter. See [`HasData`] for more information about the type
+/// parameter's purpose.
+///
+/// When using this type you can skip the [`WasiClocksView`] trait, for
+/// example.
+///
+/// # Examples
+///
+/// ```
+/// use wasmtime::component::{Linker, ResourceTable};
+/// use wasmtime::{Engine, Result, Config};
+/// use wasmtime_wasi::clocks::*;
+///
+/// struct MyStoreState {
+///     table: ResourceTable,
+///     clocks: WasiClocksCtx,
+/// }
+///
+/// fn main() -> Result<()> {
+///     let mut config = Config::new();
+///     config.async_support(true);
+///     let engine = Engine::new(&config)?;
+///     let mut linker = Linker::new(&engine);
+///
+///     wasmtime_wasi::p2::bindings::clocks::monotonic_clock::add_to_linker::<MyStoreState, WasiClocks>(
+///         &mut linker,
+///         |state| WasiClocksCtxView {
+///             table: &mut state.table,
+///             ctx: &mut state.clocks,
+///         },
+///     )?;
+///     Ok(())
+/// }
+/// ```
 pub struct WasiClocks;
 
 impl HasData for WasiClocks {
     type Data<'a> = WasiClocksCtxView<'a>;
 }
 
 pub struct WasiClocksCtx {
-    pub wall_clock: Box<dyn HostWallClock + Send>,
-    pub monotonic_clock: Box<dyn HostMonotonicClock + Send>,
+    pub(crate) wall_clock: Box<dyn HostWallClock + Send>,
+    pub(crate) monotonic_clock: Box<dyn HostMonotonicClock + Send>,
 }
 
 impl Default for WasiClocksCtx {

crates/wasi/src/filesystem.rs

@@ -8,6 +8,44 @@ use std::sync::Arc;
 use tracing::debug;
 use wasmtime::component::{HasData, Resource, ResourceTable};
 
+/// A helper struct which implements [`HasData`] for the `wasi:filesystem` APIs.
+///
+/// This can be useful when directly calling `add_to_linker` functions directly,
+/// such as [`wasmtime_wasi::p2::bindings::filesystem::types::add_to_linker`] as
+/// the `D` type parameter. See [`HasData`] for more information about the type
+/// parameter's purpose.
+///
+/// When using this type you can skip the [`WasiFilesystemView`] trait, for
+/// example.
+///
+/// # Examples
+///
+/// ```
+/// use wasmtime::component::{Linker, ResourceTable};
+/// use wasmtime::{Engine, Result, Config};
+/// use wasmtime_wasi::filesystem::*;
+///
+/// struct MyStoreState {
+///     table: ResourceTable,
+///     filesystem: WasiFilesystemCtx,
+/// }
+///
+/// fn main() -> Result<()> {
+///     let mut config = Config::new();
+///     config.async_support(true);
+///     let engine = Engine::new(&config)?;
+///     let mut linker = Linker::new(&engine);
+///
+///     wasmtime_wasi::p2::bindings::filesystem::types::add_to_linker::<MyStoreState, WasiFilesystem>(
+///         &mut linker,
+///         |state| WasiFilesystemCtxView {
+///             table: &mut state.table,
+///             ctx: &mut state.filesystem,
+///         },
+///     )?;
+///     Ok(())
+/// }
+/// ```
 pub struct WasiFilesystem;
 
 impl HasData for WasiFilesystem {
@@ -16,8 +54,8 @@ impl HasData for WasiFilesystem {
 
 #[derive(Clone, Default)]
 pub struct WasiFilesystemCtx {
-    pub allow_blocking_current_thread: bool,
-    pub preopens: Vec<(Dir, String)>,
+    pub(crate) allow_blocking_current_thread: bool,
+    pub(crate) preopens: Vec<(Dir, String)>,
 }
 
 pub struct WasiFilesystemCtxView<'a> {

crates/wasi/src/random.rs

@@ -1,16 +1,50 @@
 use cap_rand::{Rng as _, RngCore, SeedableRng as _};
 use wasmtime::component::HasData;
 
+/// A helper struct which implements [`HasData`] for the `wasi:random` APIs.
+///
+/// This can be useful when directly calling `add_to_linker` functions directly,
+/// such as [`wasmtime_wasi::p2::bindings::random::random::add_to_linker`] as
+/// the `D` type parameter. See [`HasData`] for more information about the type
+/// parameter's purpose.
+///
+/// When using this type you can skip the [`WasiRandomView`] trait, for
+/// example.
+///
+/// # Examples
+///
+/// ```
+/// use wasmtime::component::Linker;
+/// use wasmtime::{Engine, Result, Config};
+/// use wasmtime_wasi::random::*;
+///
+/// struct MyStoreState {
+///     random: WasiRandomCtx,
+/// }
+///
+/// fn main() -> Result<()> {
+///     let mut config = Config::new();
+///     config.async_support(true);
+///     let engine = Engine::new(&config)?;
+///     let mut linker = Linker::new(&engine);
+///
+///     wasmtime_wasi::p2::bindings::random::random::add_to_linker::<MyStoreState, WasiRandom>(
+///         &mut linker,
+///         |state| &mut state.random,
+///     )?;
+///     Ok(())
+/// }
+/// ```
 pub struct WasiRandom;
 
 impl HasData for WasiRandom {
     type Data<'a> = &'a mut WasiRandomCtx;
 }
 
 pub struct WasiRandomCtx {
-    pub random: Box<dyn RngCore + Send>,
-    pub insecure_random: Box<dyn RngCore + Send>,
-    pub insecure_random_seed: u128,
+    pub(crate) random: Box<dyn RngCore + Send>,
+    pub(crate) insecure_random: Box<dyn RngCore + Send>,
+    pub(crate) insecure_random_seed: u128,
 }
 
 impl Default for WasiRandomCtx {

crates/wasi/src/sockets/mod.rs

@@ -14,6 +14,44 @@ pub(crate) use tcp::NonInheritedOptions;
 pub use tcp::TcpSocket;
 pub use udp::UdpSocket;
 
+/// A helper struct which implements [`HasData`] for the `wasi:sockets` APIs.
+///
+/// This can be useful when directly calling `add_to_linker` functions directly,
+/// such as [`wasmtime_wasi::p2::bindings::sockets::tcp::add_to_linker`] as the
+/// `D` type parameter. See [`HasData`] for more information about the type
+/// parameter's purpose.
+///
+/// When using this type you can skip the [`WasiSocketsView`] trait, for
+/// example.
+///
+/// # Examples
+///
+/// ```
+/// use wasmtime::component::{Linker, ResourceTable};
+/// use wasmtime::{Engine, Result, Config};
+/// use wasmtime_wasi::sockets::*;
+///
+/// struct MyStoreState {
+///     table: ResourceTable,
+///     sockets: WasiSocketsCtx,
+/// }
+///
+/// fn main() -> Result<()> {
+///     let mut config = Config::new();
+///     config.async_support(true);
+///     let engine = Engine::new(&config)?;
+///     let mut linker = Linker::new(&engine);
+///
+///     wasmtime_wasi::p2::bindings::sockets::tcp::add_to_linker::<MyStoreState, WasiSockets>(
+///         &mut linker,
+///         |state| WasiSocketsCtxView {
+///             ctx: &mut state.sockets,
+///             table: &mut state.table,
+///         },
+///     )?;
+///     Ok(())
+/// }
+/// ```
 pub struct WasiSockets;
 
 impl HasData for WasiSockets {