Comments and renames

derive/src/codegen.rs

@@ -1,8 +1,8 @@
-use crate::parser::{ExtDefinition, ExternalFunc};
+use crate::parser::{ImplBlockDef, FuncDef};
 use proc_macro2::{Ident, Literal, Span, TokenStream};
 use quote::{quote, quote_spanned, ToTokens};
 
-pub fn codegen(ext_def: &ExtDefinition, to: &mut TokenStream) {
+pub fn codegen(ext_def: &ImplBlockDef, to: &mut TokenStream) {
     let mut externals = TokenStream::new();
     let mut module_resolver = TokenStream::new();
 
@@ -44,12 +44,12 @@ pub fn codegen(ext_def: &ExtDefinition, to: &mut TokenStream) {
     .to_tokens(to);
 }
 
-fn emit_dispatch_func_arm(func: &ExternalFunc) -> TokenStream {
+fn emit_dispatch_func_arm(func: &FuncDef) -> TokenStream {
     let index = func.index as usize;
     let return_ty_span = func.return_ty.clone().unwrap_or_else(|| Span::call_site());
 
     let mut unmarshall_args = TokenStream::new();
-    for (i, param) in func.args.iter().enumerate() {
+    for (i, param) in func.params.iter().enumerate() {
         let param_span = param.ident.span();
         let ident = &param.ident;
 
@@ -71,10 +71,10 @@ fn emit_dispatch_func_arm(func: &ExternalFunc) -> TokenStream {
     };
 
     let call = {
-        let args = func.args.iter().map(|param| param.ident.clone());
+        let params = func.params.iter().map(|param| param.ident.clone());
         let name = Ident::new(&func.name, Span::call_site());
         quote! {
-            #name( #(#args),* )
+            #name( #(#params),* )
         }
     };
     (quote! {
@@ -86,7 +86,7 @@ fn emit_dispatch_func_arm(func: &ExternalFunc) -> TokenStream {
     })
 }
 
-fn derive_externals(ext_def: &ExtDefinition, to: &mut TokenStream) {
+fn derive_externals(ext_def: &ImplBlockDef, to: &mut TokenStream) {
     let (impl_generics, ty_generics, where_clause) = ext_def.generics.split_for_impl();
     let ty = &ext_def.ty;
 
@@ -114,25 +114,25 @@ fn derive_externals(ext_def: &ExtDefinition, to: &mut TokenStream) {
     .to_tokens(to);
 }
 
-fn emit_resolve_func_arm(func: &ExternalFunc) -> TokenStream {
+fn emit_resolve_func_arm(func: &FuncDef) -> TokenStream {
     let index = func.index as usize;
     let string_ident = &func.name;
     let return_ty_span = func.return_ty.clone().unwrap_or_else(|| Span::call_site());
 
     let call = {
-        let args = func.args.iter().map(|param| {
+        let params = func.params.iter().map(|param| {
             let ident = param.ident.clone();
             let span = param.ident.span();
             quote_spanned! {span=> #ident.unwrap() }
         });
         let name = Ident::new(&func.name, Span::call_site());
         quote! {
-            Self::#name( panic!(), #(#args),* )
+            Self::#name( panic!(), #(#params),* )
         }
     };
 
     let init = func
-        .args
+        .params
         .iter()
         .map(|param| {
             let ident = &param.ident;
@@ -143,7 +143,7 @@ fn emit_resolve_func_arm(func: &ExternalFunc) -> TokenStream {
         .collect::<Vec<_>>();
 
     let params_materialized_tys = func
-        .args
+        .params
         .iter()
         .map(|param| {
             let ident = &param.ident;
@@ -181,7 +181,7 @@ fn emit_resolve_func_arm(func: &ExternalFunc) -> TokenStream {
     }
 }
 
-fn derive_module_resolver(ext_def: &ExtDefinition, to: &mut TokenStream) {
+fn derive_module_resolver(ext_def: &ImplBlockDef, to: &mut TokenStream) {
     let (impl_generics, ty_generics, where_clause) = ext_def.generics.split_for_impl();
     let ty = &ext_def.ty;
 

derive/src/parser.rs

@@ -1,35 +1,40 @@
 use syn::{spanned::Spanned, FnArg, Ident, ImplItem, ImplItemMethod, ItemImpl, ReturnType};
 
+/// A parameter.
 #[derive(Clone)]
 pub struct Param {
     /// A generated identifier used to name temporary variables
     /// used for storing this parameter in generated code.
+    ///
+    /// This ident is used primary used for its' span.
     pub ident: syn::Ident,
 }
 
-pub struct ExternalFunc {
+/// A function definition parsed from an impl block.
+pub struct FuncDef {
     /// Assigned index of this function.
     pub index: u32,
     pub name: String,
-    // TODO: Rename args to params
-    pub args: Vec<Param>,
+    pub params: Vec<Param>,
     pub return_ty: Option<proc_macro2::Span>,
 }
 
-/// The core structure that contains the list of all functions
-/// and the data required for implementing a trait.
-pub struct ExtDefinition {
-    /// List of all external functions.
-    pub funcs: Vec<ExternalFunc>,
+/// This is the core data structure which contains the list of all defined functions
+/// and the data required for the code generator (e.g. for implementing a trait).
+pub struct ImplBlockDef {
+    /// List of all defined external functions.
+    pub funcs: Vec<FuncDef>,
     /// The generics required to implement a trait for this type.
     pub generics: syn::Generics,
-    /// The type declaration to implement to implement a trait, most typically
+    /// The type declaration to implement a trait, most typically
     /// represented by a structure.
+    ///
+    /// E.g.: `Foo<'a>`, `()`
     pub ty: Box<syn::Type>,
 }
 
 /// Parse an incoming stream of tokens into externalities definition.
-pub fn parse(input: proc_macro2::TokenStream) -> Result<ExtDefinition, ()> {
+pub fn parse(input: proc_macro2::TokenStream) -> Result<ImplBlockDef, ()> {
     let item_impl = syn::parse2::<syn::ItemImpl>(input).map_err(|_| ())?;
 
     let mut funcs = vec![];
@@ -40,7 +45,7 @@ pub fn parse(input: proc_macro2::TokenStream) -> Result<ExtDefinition, ()> {
                 let index = funcs.len() as u32;
 
                 // self TODO: handle this properly
-                let args = sig
+                let params = sig
                     .decl
                     .inputs
                     .iter()
@@ -58,10 +63,10 @@ pub fn parse(input: proc_macro2::TokenStream) -> Result<ExtDefinition, ()> {
                     ReturnType::Type(_, ty) => Some(ty.span()),
                 };
 
-                funcs.push(ExternalFunc {
+                funcs.push(FuncDef {
                     index,
                     name: sig.ident.to_string(),
-                    args,
+                    params,
                     return_ty,
                 });
             }
@@ -69,7 +74,7 @@ pub fn parse(input: proc_macro2::TokenStream) -> Result<ExtDefinition, ()> {
         }
     }
 
-    Ok(ExtDefinition {
+    Ok(ImplBlockDef {
         funcs,
         generics: item_impl.generics.clone(),
         ty: item_impl.self_ty.clone(),