Merge pull request #547 from derekdreery/extra_docs

Extra docs

crates/backend/src/ast.rs

@@ -2,31 +2,54 @@ use proc_macro2::{Ident, Span};
 use shared;
 use syn;
 
+/// An abstract syntax tree representing a rust program. Contains
+/// extra information for joining up this rust code with javascript.
 #[cfg_attr(feature = "extra-traits", derive(Debug, PartialEq))]
 #[derive(Default)]
 pub struct Program {
+    /// rust -> js interfaces
     pub exports: Vec<Export>,
+    /// js -> rust interfaces
     pub imports: Vec<Import>,
+    /// rust enums
     pub enums: Vec<Enum>,
+    /// rust structs
     pub structs: Vec<Struct>,
+    /// rust type aliases
     pub type_aliases: Vec<TypeAlias>,
+    /// rust consts
     pub consts: Vec<Const>,
 }
 
+/// A rust to js interface. Allows interaction with rust objects/functions
+/// from javascript.
 #[cfg_attr(feature = "extra-traits", derive(Debug, PartialEq, Eq))]
 pub struct Export {
+    /// The javascript class name.
     pub class: Option<Ident>,
+    /// The type of `self` (either `self`, `&self`, or `&mut self`)
     pub method_self: Option<MethodSelf>,
+    /// The name of the constructor function (e.g. new).
+    ///
+    /// This allows javascript to expose an `Object` interface, where calling
+    /// the constructor maps correctly to rust.
     pub constructor: Option<String>,
+    /// The rust function
     pub function: Function,
+    /// Comments extracted from the rust source.
     pub comments: Vec<String>,
+    /// The name of the rust function/method on the rust side.
     pub rust_name: Ident,
 }
 
+/// The 3 types variations of `self`.
 #[cfg_attr(feature = "extra-traits", derive(Debug, PartialEq, Eq))]
 pub enum MethodSelf {
+    /// `self`
     ByValue,
+    /// `&mut self`
     RefMutable,
+    /// `&self`
     RefShared,
 }
 
@@ -219,6 +242,8 @@ impl Function {
 }
 
 impl Export {
+    /// Mangles a rust -> javascript export, so that the created Ident will be unique over function
+    /// name and class name, if the function belongs to a javascript class.
     pub(crate) fn rust_symbol(&self) -> Ident {
         let mut generated_name = String::from("__wasm_bindgen_generated");
         if let Some(class) = &self.class {
@@ -230,6 +255,9 @@ impl Export {
         Ident::new(&generated_name, Span::call_site())
     }
 
+    /// This is the name of the shim function that gets exported and takes the raw
+    /// ABI form of its arguments and converts them back into their normal,
+    /// "high level" form before calling the actual function.
     pub(crate) fn export_name(&self) -> String {
         let fn_name = self.function.name.to_string();
         match &self.class {
@@ -310,6 +338,7 @@ impl Import {
 }
 
 impl ImportKind {
+    /// Whether this type can be inside an `impl` block.
     pub fn fits_on_impl(&self) -> bool {
         match *self {
             ImportKind::Function(_) => true,
@@ -330,10 +359,14 @@ impl ImportKind {
 }
 
 impl ImportFunction {
+    /// If the rust object has a `fn xxx(&self) -> MyType` method, get the name for a getter in
+    /// javascript (in this case `xxx`, so you can write `val = obj.xxx`)
     fn infer_getter_property(&self) -> String {
         self.function.name.to_string()
     }
 
+    /// If the rust object has a `fn set_xxx(&mut self, MyType)` style method, get the name
+    /// for a setter in javascript (in this case `xxx`, so you can write `obj.xxx = val`)
     fn infer_setter_property(&self) -> String {
         let name = self.function.name.to_string();
         assert!(name.starts_with("set_"), "setters must start with `set_`");