Add some more doc comments

crates/cli/src/bin/wasm2es6js.rs

@@ -3,7 +3,6 @@ extern crate serde_derive;
 extern crate docopt;
 extern crate parity_wasm;
 extern crate wasm_bindgen_cli_support;
-#[macro_use]
 extern crate failure;
 
 use std::fs::File;

src/closure.rs

@@ -174,6 +174,7 @@ impl<T> Drop for Closure<T>
 ///
 /// This trait is not stable and it's not recommended to use this in bounds or
 /// implement yourself.
+#[doc(hidden)]
 pub unsafe trait WasmClosure: 'static {
     fn describe();
 

src/convert.rs

@@ -13,26 +13,59 @@ use describe::*;
 #[cfg(feature = "std")]
 use std::prelude::v1::*;
 
-#[derive(PartialEq, Eq, Copy, Clone)]
-pub struct Descriptor {
-    #[doc(hidden)]
-    pub __x: [u8; 4],
-}
-
+/// A trait for anything that can be converted into a type that can cross the
+/// wasm ABI directly, eg `u32` or `f64`.
+///
+/// This is the opposite operation as `FromWasmAbi` and `Ref[Mut]FromWasmAbi`.
 pub trait IntoWasmAbi: WasmDescribe {
+    /// The wasm ABI type that this converts into when crossing the ABI
+    /// boundary.
     type Abi: WasmAbi;
+
+    /// Convert `self` into `Self::Abi` so that it can be sent across the wasm
+    /// ABI boundary.
     fn into_abi(self, extra: &mut Stack) -> Self::Abi;
 }
 
+/// A trait for anything that can be recovered by-value from the wasm ABI
+/// boundary, eg a Rust `u8` can be recovered from the wasm ABI `u32` type.
+///
+/// This is the by-value variant of the opposite operation as `IntoWasmAbi`.
 pub trait FromWasmAbi: WasmDescribe {
+    /// The wasm ABI type that this converts from when coming back out from the
+    /// ABI boundary.
     type Abi: WasmAbi;
-    unsafe fn from_abi(js: Self::Abi, extra: &mut Stack) -> Self;
 
+    /// Recover a `Self` from `Self::Abi`.
+    ///
+    /// # Safety
+    ///
+    /// This is only safe to call when -- and implementations may assume that --
+    /// the supplied `Self::Abi` was previously generated by a call to `<Self as
+    /// IntoWasmAbi>::into_abi()` or the moral equivalent in JS.
+    unsafe fn from_abi(js: Self::Abi, extra: &mut Stack) -> Self;
 }
 
+/// A trait for anything that can be recovered as some sort of shared reference
+/// from the wasm ABI boundary.
+///
+/// This is the shared reference variant of the opposite operation as
+/// `IntoWasmAbi`.
 pub trait RefFromWasmAbi: WasmDescribe {
+    /// The wasm ABI type references to `Self` are recovered from.
     type Abi: WasmAbi;
+
+    /// The type that holds the reference to `Self` for the duration of the
+    /// invocation of the function that has an `&Self` parameter. This is
+    /// required to ensure that the lifetimes don't persist beyond one function
+    /// call, and so that they remain anonymous.
     type Anchor: Deref<Target=Self>;
+
+    /// Recover a `Self::Anchor` from `Self::Abi`.
+    ///
+    /// # Safety
+    ///
+    /// Same as `FromWasmAbi::from_abi`.
     unsafe fn ref_from_abi(js: Self::Abi, extra: &mut Stack) -> Self::Anchor;
 }
 
@@ -142,7 +175,7 @@ impl IntoWasmAbi for char {
 
 impl FromWasmAbi for char {
     type Abi = u32;
-    unsafe fn from_abi(js: u32, _extra: &mut Stack) -> char { 
+    unsafe fn from_abi(js: u32, _extra: &mut Stack) -> char {
         char::from_u32_unchecked(js)
     }
 }
@@ -539,4 +572,4 @@ stack_closures! {
     (A B C D E)
     (A B C D E F)
     (A B C D E F G)
-}
+}