docs(ul/dl): method features and general info

* add method listing for various categories, like 'downloads' and
  'uploads'
* add general information on how to do downloads and uploads using
  various protocols

Fixes #28

gen/youtube3/README.md

@@ -27,6 +27,18 @@ Handle the following *Resources* with ease from the central [hub](http://byron.g
 * [videos](http://byron.github.io/google-apis-rs/youtube3/struct.Video.html) ([*delete*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoDeleteMethodBuilder.html), [*get rating*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoGetRatingMethodBuilder.html), [*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoInsertMethodBuilder.html), [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoListMethodBuilder.html), [*rate*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoRateMethodBuilder.html) and [*update*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoUpdateMethodBuilder.html))
 * watermarks ([*set*](http://byron.github.io/google-apis-rs/youtube3/struct.WatermarkSetMethodBuilder.html) and [*unset*](http://byron.github.io/google-apis-rs/youtube3/struct.WatermarkUnsetMethodBuilder.html))
 
+Upload supported by ...
+
+* [*set watermarks*](http://byron.github.io/google-apis-rs/youtube3/struct.WatermarkSetMethodBuilder.html)
+* [*insert channel banners*](http://byron.github.io/google-apis-rs/youtube3/struct.ChannelBannerInsertMethodBuilder.html)
+* [*set thumbnails*](http://byron.github.io/google-apis-rs/youtube3/struct.ThumbnailSetMethodBuilder.html)
+* [*insert videos*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoInsertMethodBuilder.html)
+
+Subscription supported by ...
+
+* [*list playlist items*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistItemListMethodBuilder.html)
+
+
 Everything else about the *YouTube* *v3* API can be found at the
 [official documentation site](https://developers.google.com/youtube/v3).
 
@@ -135,6 +147,10 @@ the doit() methods, or handed as possibly intermediate results to either the
 When delegates handle errors or intermediate values, they may have a chance to instruct the system to retry. This 
 makes the system potentially resilient to all kinds of errors.
 
+## About Uploads and Downlods
+
+TODO: 'alt' media for downloads, custom methods for uploads (simple, resumable)
+
 ## About Customization/Callbacks
 
 You may alter the way an `doit()` method is called by providing a [delegate](http://byron.github.io/google-apis-rs/youtube3/cmn/trait.Delegate.html) to the 

gen/youtube3/src/lib.rs

@@ -26,6 +26,18 @@
 //! * [videos](struct.Video.html) ([*delete*](struct.VideoDeleteMethodBuilder.html), [*get rating*](struct.VideoGetRatingMethodBuilder.html), [*insert*](struct.VideoInsertMethodBuilder.html), [*list*](struct.VideoListMethodBuilder.html), [*rate*](struct.VideoRateMethodBuilder.html) and [*update*](struct.VideoUpdateMethodBuilder.html))
 //! * watermarks ([*set*](struct.WatermarkSetMethodBuilder.html) and [*unset*](struct.WatermarkUnsetMethodBuilder.html))
 //! 
+//! Upload supported by ...
+//! 
+//! * [*set watermarks*](struct.WatermarkSetMethodBuilder.html)
+//! * [*insert channel banners*](struct.ChannelBannerInsertMethodBuilder.html)
+//! * [*set thumbnails*](struct.ThumbnailSetMethodBuilder.html)
+//! * [*insert videos*](struct.VideoInsertMethodBuilder.html)
+//! 
+//! Subscription supported by ...
+//! 
+//! * [*list playlist items*](struct.PlaylistItemListMethodBuilder.html)
+//! 
+//! 
 //! Everything else about the *YouTube* *v3* API can be found at the
 //! [official documentation site](https://developers.google.com/youtube/v3).
 //! 
@@ -137,6 +149,10 @@
 //! When delegates handle errors or intermediate values, they may have a chance to instruct the system to retry. This 
 //! makes the system potentially resilient to all kinds of errors.
 //! 
+//! ## About Uploads and Downlods
+//! 
+//! TODO: 'alt' media for downloads, custom methods for uploads (simple, resumable)
+//! 
 //! ## About Customization/Callbacks
 //! 
 //! You may alter the way an `doit()` method is called by providing a [delegate](cmn/trait.Delegate.html) to the 

src/mako/lib/lib.mako

@@ -4,7 +4,8 @@
                       PART_MARKER_TRAIT, RESOURCE_MARKER_TRAIT, METHOD_BUILDER_MARKERT_TRAIT, 
                       find_fattest_resource, build_all_params, pass_through, parts_from_params,
                       REQUEST_MARKER_TRAIT, RESPONSE_MARKER_TRAIT, supports_scopes, to_api_version,
-                      to_fqan)  %>\
+                      to_fqan, METHODS_RESOURCE, ADD_PARAM_MEDIA_EXAMPLE, PROTOCOL_TYPE_INFO, enclose_in,
+                      upload_action_fn)  %>\
 <%namespace name="util" file="util.mako"/>\
 <%namespace name="mbuild" file="mbuild.mako"/>\
 
@@ -38,6 +39,17 @@
     api_version = to_api_version(version)
     if api_version[0].isdigit():
         api_version = 'v' + api_version
+
+
+    upload_methods, download_methods, subscription_methods = list(), list(), list()
+    for m in c.fqan_map.values():
+        for array, param in ((download_methods, 'supportsMediaDownload'),
+                             (upload_methods, 'supportsMediaUpload'),
+                             (subscription_methods, 'supportsSubscription')):
+            if m.get(param, False):
+                array.append(m)
+    # end for each method
+    header_methods = (('Upload', upload_methods), ('Download', download_methods), ('Subscription', subscription_methods))
 %>\
 % if rust_doc:
 This documentation was generated from *${util.canonical_name()}* crate version *${cargo.build_version}*.
@@ -62,6 +74,23 @@ Handle the following *Resources* with ease from the central ${link('hub', hub_ur
 * ${md_resource} (${put_and(md_methods)})
 % endfor
 
+% for method_type, methods in header_methods:
+% if methods:
+${method_type} supported by ...
+
+% for m in methods:
+<% 
+    _, resource, method = activity_split(m.id)
+    name_parts = [split_camelcase_s(method)]
+    if resource != METHODS_RESOURCE:
+        name_parts.append(split_camelcase_s(resource))
+%>\
+* ${link('*%s*' % ' '.join(name_parts), 'struct.%s.html' % mb_type(resource, method))}
+% endfor ## for each method
+
+% endif  ## if methods
+% endfor ## for each method type
+
 % if documentationLink:
 Everything else about the *${util.canonical_name()}* *${api_version}* API can be found at the
 [official documentation site](${documentationLink}).
@@ -133,8 +162,15 @@ When delegates handle errors or intermediate values, they may have a chance to i
 makes the system potentially resilient to all kinds of errors.
 
 ${'##'} About Uploads and Downlods
+If a method supports downloads, the response body, which is part of the ${link('Result', 'cmn/enum.Result.html')}, should be
+read by you to obtain the media.
+If such a method also supports a ${link('Response Result', 'cmn/trait.ResponseResult.html')}, it will return that by default.
+You can see it as meta-data for the actual media. To trigger a media download, you will have to set up the builder by making
+this call: `${ADD_PARAM_MEDIA_EXAMPLE}`.
 
-TODO: 'alt' media for downloads, custom methods for uploads (simple, resumable)
+Methods supporting uploads can do so using up to ${len(PROTOCOL_TYPE_INFO)} different protocols: 
+${put_and(md_italic(PROTOCOL_TYPE_INFO.keys()))}. The distinctiveness of each is represented by customized 
+`${api.terms.action}(...)` methods, which are then named ${put_and(enclose_in('`', ("%s(...)" % upload_action_fn(api.terms.upload_action, v['suffix']) for v in PROTOCOL_TYPE_INFO.values())))} respectively.
 
 ${'##'} About Customization/Callbacks
 

src/mako/lib/mbuild.mako

@@ -9,7 +9,7 @@
                       hub_type_params_s, method_media_params, enclose_in, mb_type_bounds, method_response,
                       METHOD_BUILDER_MARKERT_TRAIT, pass_through, markdown_rust_block, parts_from_params,
                       DELEGATE_PROPERTY_NAME, struct_type_bounds_s, supports_scopes, scope_url_to_variant,
-                      re_find_replacements)
+                      re_find_replacements, ADD_PARAM_FN, ADD_PARAM_MEDIA_EXAMPLE, upload_action_fn)
 
     def get_parts(part_prop):
         if not part_prop:
@@ -34,9 +34,6 @@
         if is_repeated_property(p):
             fn_name = 'add_' + fn_name
         return fn_name
-
-    add_param_fn = 'param'
-
 %>\
 <%namespace name="util" file="util.mako"/>\
 <%namespace name="lib" file="lib.mako"/>\
@@ -65,8 +62,8 @@ ${m.description | rust_doc_comment}
 ///
 % endif
 % if m.get('supportsMediaDownload', False):
-/// This method supports **media download**. To enable it, set the *alt* parameter to *media*, .i.e.
-/// `.${add_param_fn}("alt", "media")`.
+/// This method supports **media download**. To enable it, adjust the builder like this:
+/// `${ADD_PARAM_MEDIA_EXAMPLE}`.
 % if response_schema:
 /// Please note that due to missing multi-part support on the server side, you will only receive the media,
 /// but not the `${response_schema.id}` structure that you would usually get. The latter will be a default value.
@@ -148,7 +145,7 @@ ${self._setter_fn(resource, method, m, p, part_prop, ThisType, c)}\
     /// * *${opn}* (${op.location}-${op.type}) - ${op.description}
     % endfor
     % endif
-    pub fn ${add_param_fn}<T>(mut self, name: T, value: T) -> ${ThisType}
+    pub fn ${ADD_PARAM_FN}<T>(mut self, name: T, value: T) -> ${ThisType}
                                                         where T: Str {
         self.${api.properties.params}.insert(name.as_slice().to_string(), value.as_slice().to_string());
         self
@@ -285,7 +282,7 @@ ${self._setter_fn(resource, method, m, p, part_prop, ThisType, c)}\
         index = -1
         if media_params[-1].max_size < 100*1024*1024:
             index = 0
-        action_name = api.terms.upload_action + media_params[index].type.suffix
+        action_name = upload_action_fn(api.terms.upload_action, media_params[index].type.suffix)
     else:
         action_name = api.terms.action
     action_args = media_params and media_params[-1].type.example_value or ''
@@ -754,7 +751,7 @@ if enable_resource_parsing \
     % for item_name, item in p.info.iteritems():
     /// * *${split_camelcase_s(item_name)}*: ${isinstance(item, (list, tuple)) and put_and(enclose_in("'", item)) or str(item)}
     % endfor
-    pub fn ${api.terms.upload_action}${p.type.suffix}<${mtype_param}>(self, ${p.type.arg_name}: ${mtype_param}, mime_type: mime::Mime) -> ${rtype}
+    pub fn ${upload_action_fn(api.terms.upload_action, p.type.suffix)}<${mtype_param}>(self, ${p.type.arg_name}: ${mtype_param}, mime_type: mime::Mime) -> ${rtype}
                 where ${mtype_param}: ${mtype_where} {
         self.${api.terms.action}(\
         % for _ in range(0, loop.index):

src/mako/lib/util.py

@@ -54,6 +54,9 @@ INS_METHOD = 'insert'
 DEL_METHOD = 'delete'
 METHODS_RESOURCE = 'methods'
 
+ADD_PARAM_FN = 'param'
+ADD_PARAM_MEDIA_EXAMPLE = "." + ADD_PARAM_FN + '("alt", "media")'
+
 SPACES_PER_TAB = 4
 
 NESTED_TYPE_SUFFIX = 'item'
@@ -821,6 +824,9 @@ def get_word(d, n, e = ''):
 def property(n):
     return '_' + mangle_ident(n)
 
+def upload_action_fn(upload_action_term, suffix):
+    return upload_action_term + suffix
+
 # n = 'foo.bar.Baz' -> 'FooBarBaz'
 def dot_sep_to_canonical_type_name(n):
     return ''.join(canonical_type_name(singular(t)) for t in n.split('.'))