Add docs from gitbook to crates (#18)

* add docs from gitbook to crates

* image move and crate name

* update: more doc

* update: more docs

---------
Co-authored-by: Erik Chi <[email protected]>

Cargo.toml

@@ -7,7 +7,7 @@ resolver="2"
 
 
 [workspace.package]
-authors = ["cerikccc@gmail.com", "gaukas", "jmwample", "ewust"]
+authors = ["hi@erikchi.com", "gaukas", "jmwample", "ewust"]
 description = "Water WebAssembly Transport Executor for rust"
 edition = "2021"
 # documentation = "https://example.com/bar"

README.md

@@ -43,11 +43,11 @@ If you quoted or used our work, please cite our paper [Just add WATER: WebAssemb
 
 The repo contains 2 main components:
 1. A Rust crate [`water`](https://github.com/erikziyunchi/water-rs/tree/main/crates/water) runtime library used to interact with `.wasm` WebAssembly Transport Modules(WATM).
-2. A Rust crate [`water-wasm-crate`](https://github.com/erikziyunchi/water-rs/tree/main/crates/wasm) for WATM-development where developers can easily create their own `.wasm`.
+2. A Rust crate [`water_wasm`](https://github.com/erikziyunchi/water-rs/tree/main/crates/wasm) for WATM-development where developers can easily create their own `.wasm`.
 
 Also include examples for demonstration of usage:
 1. A standalone cli tool which can be used to load a `.wasm` WATM directly and run it. See [water-rs/tree/main/examples/clients/cli](https://github.com/erikziyunchi/water-rs/tree/main/examples/clients/cli).
-2. A few examples WATM implementations with `water-wasm-crate`, see [water-rs/tree/main/examples/water_bins](https://github.com/erikziyunchi/water-rs/tree/main/examples/water_bins).
+2. A few examples WATM implementations with `water_wasm` crate, see [water-rs/tree/main/examples/water_bins](https://github.com/erikziyunchi/water-rs/tree/main/examples/water_bins).
 3. Examples of using the above WATM examples with our `water` library, see [tests](https://github.com/erikziyunchi/water-rs/tree/main/tests/tests) for usage.
 
 ## Running tests
@@ -61,4 +61,4 @@ cargo test -p <crate_name> --verbose
 
 # run a single test (or test matching name prefix) in a single crate
 cargo test -p <crate_name> --verbose -- <test_name>
-```
+```

crates/wasm/src/config.rs

@@ -1,6 +1,11 @@
+//! This module contains the default config struct for the WATM module
+//!
+//! The config should be read from a .json file by the WATM module and setup the
+//! corresponding connection addresses and ports
+
 use super::*;
 
-// A Config currently contains the local + remote ip & port
+/// A Config currently contains the local + remote ip & port + bypass flag
 #[derive(Debug, Deserialize, Clone)]
 pub struct Config {
     pub remote_address: String,
@@ -16,7 +21,7 @@ impl Default for Config {
     }
 }
 
-// implement a constructor for the config
+/// implement a constructor for the config
 impl Config {
     pub fn new() -> Self {
         Config {
@@ -29,8 +34,9 @@ impl Config {
     }
 }
 
-// ============ Some implementation for V1 ============
-// A config struct that shares between your host & wasm to establish a connection
+// ============ Below are some implementations for V1 ============
+
+/// A config struct that shares between your host & wasm to establish a connection
 // #[cfg(feature = "v1")]
 #[derive(Serialize, Deserialize)]
 pub struct StreamConfigV1 {

crates/wasm/src/connections.rs

@@ -1,3 +1,14 @@
+//! This module contains the Connection struct, which is the main struct for a connection
+//! that contains the inbound and outbound streams and the config for the connection in the WATM module.
+//!
+//! The config is a generic type that can be defined / replaced by the WATM module where it decouples
+//! the configuration of WATM module from the Host program, where if there is a config diff,
+//! we don't need to recompile the Host program to achieve our fast deloyment goal.
+//!
+//!
+//! The module also contains the ConnFile struct, which is the struct for one way of connection -- either for in / outbound
+//!
+
 use super::*;
 
 // ConnStream can store either a network stream Or a file stream
@@ -15,7 +26,7 @@ impl ConnStream {
     }
 }
 
-// ConnFile is the struct for a connection -- either for in / outbound
+/// ConnFile is the struct for a connection -- either for in / outbound
 pub struct ConnFile {
     pub fd: i32,
     pub file: Option<ConnStream>,
@@ -28,7 +39,7 @@ impl Default for ConnFile {
 }
 
 impl ConnFile {
-    // A default constructor for ConnFile
+    /// A default constructor for ConnFile
     pub fn new() -> Self {
         ConnFile { fd: -1, file: None }
     }
@@ -62,7 +73,7 @@ impl ConnFile {
     }
 }
 
-// A Connection normally contains both in & outbound streams + a config
+/// A Connection normally contains both in & outbound streams + a generic config
 pub struct Connection<T> {
     pub inbound_conn: ConnFile,
     pub outbound_conn: ConnFile,
@@ -81,7 +92,7 @@ impl<T: Default> Default for Connection<T> {
 }
 
 impl<T> Connection<T> {
-    // A default constructor
+    /// A constructor that takes in the customized config
     pub fn new(config: T) -> Self {
         Connection {
             inbound_conn: ConnFile::new(),
@@ -90,6 +101,7 @@ impl<T> Connection<T> {
         }
     }
 
+    /// Setting the inbound connection for the WATM module, which is talking to the Host
     pub fn set_inbound(&mut self, fd: i32, stream: ConnStream) {
         if fd < 0 {
             eprintln!("[WASM] > ERROR: fd is negative");
@@ -105,6 +117,7 @@ impl<T> Connection<T> {
         self.inbound_conn.file = Some(stream);
     }
 
+    /// Setting the outbound connection for the WATM module, which is talking to the remote
     pub fn set_outbound(&mut self, fd: i32, stream: ConnStream) {
         if fd < 0 {
             eprintln!("[WASM] > ERROR: fd is negative");
@@ -120,20 +133,6 @@ impl<T> Connection<T> {
         self.outbound_conn.file = Some(stream);
     }
 
-    // pub fn decoder_read_from_outbound<D: AsyncDecodeReader>(&mut self, decoder: &mut D, buf: &mut [u8]) -> Result<i64, anyhow::Error> {
-    //     debug!("[WASM] running in decoder_read_from_outbound");
-
-    //     // match self.outbound_conn.file.as_mut().unwrap() {
-    //     //     ConnStream::TcpStream(stream) => {
-    //     //         decoder.read_decrypted(stream);
-    //     //     },
-    //     //     ConnStream::File(stream) => {
-    //     //         decoder.read_decrypted(stream);
-    //     //     },
-    //     // }
-    //     Ok(decoder.poll_read_decrypted(self.outbound_conn.file.as_mut().unwrap().as_read(), buf)? as i64)
-    // }
-
     /// this _read function is triggered by the Host to read from the remote connection
     pub fn _read_from_outbound<D: Decoder>(
         &mut self,
@@ -186,6 +185,7 @@ impl<T> Connection<T> {
         Ok(len_after_decoding as i64)
     }
 
+    /// this _write function is triggered by the Host to write to the remote connection
     pub fn _write_2_outbound<E: Encoder>(
         &mut self,
         encoder: &mut E,

crates/wasm/src/decoder.rs

@@ -1,15 +1,15 @@
+//! Logic for unpackaging trait
+
 use super::*;
 
 use tokio::io::AsyncRead;
 
-// Developer Guide: Logic for packaging
-
-// A trait for a decoder, developers should implement this trait and pass it to _read_from_outbound
+/// A trait for a decoder, developers should implement this trait and pass it to _read_from_outbound
 pub trait Decoder {
     fn decode(&self, input: &[u8], output: &mut [u8]) -> Result<u32, anyhow::Error>;
 }
 
-// A default decoder that does just copy + paste
+/// A default decoder that does just copy + paste
 pub struct DefaultDecoder;
 
 impl Decoder for DefaultDecoder {

crates/wasm/src/dialer.rs

@@ -1,3 +1,11 @@
+//! This module is responsible for v1's dialing to remote server.
+//!
+//! It will create a TCP connection to the remote server by calling the
+//! Host exported helper function `connect_tcp`, and receives a file descriptor
+//! for the connection.
+//!
+//! Developers can use this lib to create a TCP connection to the remote server (ip:port from config).
+
 use super::*;
 
 use anyhow::{anyhow, Ok};

crates/wasm/src/encoder.rs

@@ -1,15 +1,15 @@
+//! Logic for packaging trait
+
 use super::*;
 
 use tokio::io::AsyncWrite;
 
-// Developer Guide: Logic for packaging
-
-// A trait for a encoder, developers should implement this trait and pass it to _write_to_outbound
+/// A trait for a encoder, developers should implement this trait and pass it to _write_to_outbound
 pub trait Encoder {
     fn encode(&self, input: &[u8], output: &mut [u8]) -> Result<u32, anyhow::Error>;
 }
 
-// A default encoder that does just copy + paste
+/// A default encoder that does just copy + paste
 pub struct DefaultEncoder;
 
 impl Encoder for DefaultEncoder {

crates/wasm/src/lib.rs

@@ -1,5 +1,5 @@
-// lib.rs
-// export all modules
+//! This lib is for a demo and ease of developing the WATM module
+
 pub mod config;
 pub mod connections;
 pub mod decoder;
@@ -34,10 +34,15 @@ use tracing::{debug, info};
 use anyhow::Result;
 use serde::{Deserialize, Serialize};
 
-// TODO: move these to speicific implementations, shouldn't be in the crate lib
 // =================== WASM Imports =====================
 extern "C" {
-    // #[link_name = "create-listen"]
+    /// These functions are exported from the host to the WATM module,
+    /// which means host must provide these functions to the WATM module.
+    ///
+    /// create a listener (specified by returned fd) -- pass ptr + size for the ip:port struct sharing to Host
+    // #[link_name = "create_listen"]
     pub fn create_listen(ptr: u32, size: u32) -> i32;
+
+    /// create a TcpStream connection (specified by returned fd) -- pass ptr + size for the ip:port struct sharing to Host
     pub fn connect_tcp(ptr: u32, size: u32) -> i32;
 }