feat(mbuild): infrastructure for method builders

Now comes the actual work of setting them up.
Additionally, the docs were decluttered to show comments only
were necessary. Now the code path to getting the hub is as concise as
possible.

gen/youtube3/README.md

@@ -74,10 +74,9 @@ extern crate "yup-oauth2" as oauth2;
 extern crate "rustc-serialize" as rustc_serialize;
 extern crate youtube3;
 
-use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
 use std::default::Default;
-
-use youtube3::YouTube;
+use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
+# use youtube3::YouTube;
 
 // Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`, 
 // among other things.

gen/youtube3/src/cmn.rs

@@ -7,7 +7,10 @@ use std::marker::MarkerTrait;
 /// The hub allows to access all resource methods more easily.
 pub trait Hub: MarkerTrait {}
 
-/// Identifies types for building methods of a particular type
+/// Identifies types for building methods of a particular resource type
+pub trait ResourceMethodsBuilder: MarkerTrait {}
+
+/// Identifies types which represent builders for a particular resource method
 pub trait MethodBuilder: MarkerTrait {}
 
 /// Identifies types which can be inserted and deleted.

src/mako/lib.rs.mako

@@ -1,6 +1,6 @@
 <% 
 	from util import (iter_nested_types, new_context, rust_comment, rust_doc_comment,
-                      rust_module_doc_comment, mb_type, hub_type)
+                      rust_module_doc_comment, rb_type, hub_type)
 	nested_schemas = list(iter_nested_types(schemas))
 
  	c = new_context(resources)
@@ -11,6 +11,7 @@
 <%namespace name="lib" file="lib/lib.mako"/>\
 <%namespace name="util" file="lib/util.mako"/>\
 <%namespace name="rbuild" file="lib/rbuild.mako"/>\
+<%namespace name="mbuild" file="lib/mbuild.mako"/>\
 <%namespace name="schema" file="lib/schema.mako"/>\
 <%block filter="rust_comment">\
 <%util:gen_info source="${self.uri}" />\
@@ -33,7 +34,7 @@ use std::marker::PhantomData;
 use std::borrow::BorrowMut;
 use std::cell::RefCell;
 
-pub use cmn::{Hub, MethodBuilder, Resource, Part, ResponseResult, RequestResult, NestedType};
+pub use cmn::{Hub, ResourceMethodsBuilder, MethodBuilder, Resource, Part, ResponseResult, RequestResult, NestedType};
 
 // ########
 // HUB ###
@@ -70,8 +71,8 @@ impl<'a, C, NC, A> ${hub_type}<C, NC, A>
     }
 
     % for resource in sorted(c.rta_map.keys()):
-    pub fn ${resource}(&'a self) -> ${mb_type(resource)}<'a, C, NC, A> {
-        ${mb_type(resource)} { hub: &self }
+    pub fn ${resource}(&'a self) -> ${rb_type(resource)}<'a, C, NC, A> {
+        ${rb_type(resource)} { hub: &self }
     }
     % endfor
 }
@@ -108,6 +109,9 @@ ${rbuild.new(resource, c)}
 // CallBuilders   ###
 // #################
 
-% for resource in c.rta_map:
+% for resource, methods in c.rta_map.iteritems():
+% for method in methods:
+${mbuild.new(resource, method, c)}
 
-% endfor
+% endfor ## method in methods
+% endfor ## resource, methods

src/mako/lib/lib.mako

@@ -76,19 +76,22 @@ ${'##'} About Customization/Callbacks
 ## Needs test_prelude.
 ###############################################################################################
 ###############################################################################################
-<%def name="test_hub(hub_type)">\
-use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
+<%def name="test_hub(hub_type, comments=True)">\
 use std::default::Default;
+use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
+# use ${util.library_name()}::${hub_type};
 
-use ${util.library_name()}::${hub_type};
-
+% if comments:
 // Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`, 
 // among other things.
+% endif
 let secret: ApplicationSecret = Default::default();
+% if comments:
 // Instantiate the authenticator. It will choose a suitable authentication flow for you, 
 // unless you replace  `None` with the desired Flow
 // Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on
 // You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage.
+% endif
 let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate,
                               hyper::Client::new(),
                               <MemoryStorage as Default>::default(), None);

src/mako/lib/mbuild.mako

@@ -0,0 +1,45 @@
+<%!
+	from util import (put_and, rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment,
+                      rb_type, mb_type, singular, hub_type)
+%>\
+<%namespace name="util" file="util.mako"/>\
+<%namespace name="lib" file="lib.mako"/>\
+
+## Creates a Call builder type
+###############################################################################################
+###############################################################################################
+<%def name="new(resource, method, c)">\
+<% hub_type_name = hub_type(canonicalName) %>\
+/// A builder for the *${method}* method supported by a *${singular(resource)}* resource.
+/// It is not used directly, but through a `${rb_type(resource)}`.
+///
+/// # Example
+///
+/// Instantiate a resource method builder
+///
+<%block filter="rust_doc_test_norun, rust_doc_comment">\
+${util.test_prelude()}\
+
+<%block filter="rust_test_fn_invisible">\
+${lib.test_hub(hub_type_name, comments=False)}\
+
+// Usually you wouldn't bind this to a variable, but keep calling methods
+// to setup your call.
+// TODO: figoure out actual arguments ... 
+// let mb = hub.${resource}().${method}(...);
+
+// Finally, execute your call and process the result
+// TODO: comment in once args are properly setup !
+// mb.do()
+</%block>
+</%block>
+pub struct ${mb_type(resource, method)}<'a, C, NC, A>
+    where NC: 'a,
+           C: 'a,
+           A: 'a, {
+
+    hub: &'a ${hub_type_name}<C, NC, A>
+}
+
+impl<'a, C, NC, A> MethodBuilder for ${mb_type(resource, method)}<'a, C, NC, A> {}
+</%def>

src/mako/lib/rbuild.mako

@@ -1,6 +1,6 @@
 <%!
 	from util import (put_and, rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment,
-                      mb_type, singular, hub_type)
+                      rb_type, singular, hub_type)
 %>\
 <%namespace name="util" file="util.mako"/>\
 <%namespace name="lib" file="lib.mako"/>\
@@ -9,9 +9,9 @@
 ###############################################################################################
 ###############################################################################################
 <%def name="new(resource, c)">\
-<% hub_type_name = hub_type(canonicalName) %>
+<% hub_type_name = hub_type(canonicalName) %>\
 /// A builder providing access to all methods supported on *${singular(resource)}* resources.
-/// It is usually not used directly, but through the `${hub_type_name}` hub.
+/// It is not used directly, but through the `${hub_type_name}` hub.
 ///
 /// # Example
 ///
@@ -21,20 +21,21 @@
 ${util.test_prelude()}\
 
 <%block filter="rust_test_fn_invisible">\
-${lib.test_hub(hub_type_name)}\
+${lib.test_hub(hub_type_name, comments=False)}\
 
-// Usually you wouldn't stick this into a variable, but keep calling `MethodBuilders`
+// Usually you wouldn't bind this to a variable, but keep calling *MethodBuilders*
 // like ${put_and(sorted('`%s(...)`' % f for f in c.rta_map[resource]))}
+// to build up your call.
 let rb = hub.${resource}();
 </%block>
 </%block>
-pub struct ${mb_type(resource)}<'a, C, NC, A>
+pub struct ${rb_type(resource)}<'a, C, NC, A>
     where NC: 'a,
            C: 'a,
            A: 'a, {
 
     hub: &'a ${hub_type_name}<C, NC, A>
 }
 
-impl<'a, C, NC, A> MethodBuilder for ${mb_type(resource)}<'a, C, NC, A> {}
+impl<'a, C, NC, A> ResourceMethodsBuilder for ${rb_type(resource)}<'a, C, NC, A> {}
 </%def>

src/mako/lib/util.py

@@ -109,6 +109,8 @@ def md_italic(l):
     return enclose_in('*', l)
 
 def singular(s):
+    if s.endswith('ies'):
+        return s[:-3]+'y'
     if s[-1] == 's':
         return s[:-1]
     return s
@@ -310,9 +312,13 @@ def to_api_version(v):
 def library_name(name, version):
     return name + to_api_version(version)
 
-# return type name of a resource builder, from a resource name
-def mb_type(r):
-    return "%sMethodBuilder" % canonical_type_name(r)
+# return type name of a resource method builder, from a resource name
+def rb_type(r):
+    return "%sMethodsBuilder" % singular(canonical_type_name(r))
+
+# return type name for a method on the given resource
+def mb_type(r, m):
+    return "%s%sMethodBuilder" % (singular(canonical_type_name(r)), m.capitalize())
 
 def hub_type(canonicalName):
     return canonical_type_name(canonicalName)

src/rust/cmn.rs

@@ -5,7 +5,10 @@ use std::marker::MarkerTrait;
 /// The hub allows to access all resource methods more easily.
 pub trait Hub: MarkerTrait {}
 
-/// Identifies types for building methods of a particular type
+/// Identifies types for building methods of a particular resource type
+pub trait ResourceMethodsBuilder: MarkerTrait {}
+
+/// Identifies types which represent builders for a particular resource method
 pub trait MethodBuilder: MarkerTrait {}
 
 /// Identifies types which can be inserted and deleted.