Add some documentation

Author: lachlansneff

lib/runtime-core/src/backend.rs

@@ -86,6 +86,10 @@ pub trait ProtectedCaller: Send + Sync {
     ///
     /// The existance of the Token parameter ensures that this can only be called from
     /// within the runtime crate.
+    ///
+    /// TODO(lachlan): Now that `get_wasm_trampoline` exists, `ProtectedCaller::call`
+    /// can be removed. That should speed up calls a little bit, since sanity checks
+    /// would only occur once.
     fn call(
         &self,
         module: &ModuleInner,
@@ -96,6 +100,9 @@ pub trait ProtectedCaller: Send + Sync {
         _: Token,
     ) -> RuntimeResult<Vec<Value>>;
 
+    /// A wasm trampoline contains the necesarry data to dynamically call an exported wasm function.
+    /// Given a particular signature index, we are returned a trampoline that is matched with that
+    /// signature and an invoke function that can call the trampoline.
     fn get_wasm_trampoline(&self, module: &ModuleInner, sig_index: SigIndex) -> Option<Wasm>;
 
     fn get_early_trapper(&self) -> Box<dyn UserTrapper>;

lib/runtime-core/src/typed_func.rs

@@ -50,6 +50,9 @@ impl fmt::Display for WasmTrapInfo {
     }
 }
 
+/// This is just an empty trait to constrict that types that
+/// can be put into the third/fourth (depending if you include lifetimes)
+/// of the `Func` struct.
 pub trait Kind {}
 
 pub type Trampoline = unsafe extern "C" fn(*mut Ctx, NonNull<vm::Func>, *const u64, *mut u64);
@@ -63,6 +66,10 @@ pub type Invoke = unsafe extern "C" fn(
     Option<NonNull<c_void>>,
 ) -> bool;
 
+
+/// TODO(lachlan): Naming TBD.
+/// This contains the trampoline and invoke functions for a specific signature,
+/// as well as the environment that the invoke function may or may not require.
 #[derive(Copy, Clone)]
 pub struct Wasm {
     trampoline: Trampoline,
@@ -84,6 +91,8 @@ impl Wasm {
     }
 }
 
+/// This type, as part of the `Func` type signature, represents a function that is created
+/// by the host.
 pub struct Host(());
 impl Kind for Wasm {}
 impl Kind for Host {}