Merge pull request #294 from fitzgen/more-docs

Fill in some doc comments + tidy up some things

crates/backend/src/ast.rs

@@ -2,7 +2,6 @@ use proc_macro2::{Ident, Span, TokenStream, TokenTree};
 use quote::ToTokens;
 use shared;
 use syn;
-use syn::AttrStyle;
 
 #[cfg_attr(feature = "extra-traits", derive(Debug, PartialEq, Eq))]
 #[derive(Default)]
@@ -1126,7 +1125,7 @@ fn extract_doc_comments(attrs: &[syn::Attribute]) -> Vec<String> {
                 // We want to filter out any Puncts so just grab the Literals
                 a.tts.clone().into_iter().filter_map(|t| match t {
                     TokenTree::Literal(lit) => {
-                        // this will always return the quoted string, we deal with 
+                        // this will always return the quoted string, we deal with
                         // that in the cli when we read in the comments
                         Some(lit.to_string())
                     },
@@ -1139,4 +1138,4 @@ fn extract_doc_comments(attrs: &[syn::Attribute]) -> Vec<String> {
     })
     //Fold up the [[String]] iter we created into Vec<String>
     .fold(vec![], |mut acc, a| {acc.extend(a); acc})
-}
+}

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)
-}
+}