docs(mbuild): docs for terms.upload methods

Also fs::File is now used with prefix, to prevent clashes.

src/mako/lib.rs.mako

@@ -34,7 +34,7 @@ use std::borrow::BorrowMut;
 use std::cell::RefCell;
 use std::default::Default;
 use std::io::{Read, Seek};
-use std::fs::File;
+use std::fs;
 
 pub use cmn::{Hub, ReadSeek, ResourceMethodsBuilder, MethodBuilder, Resource, Part, ResponseResult, RequestValue, NestedType};
 

src/mako/lib/mbuild.mako

@@ -6,7 +6,7 @@
                       schema_to_required_property, rust_copy_value_s, is_required_property,
                       hide_rust_doc_test, build_all_params, REQUEST_VALUE_PROPERTY_NAME, organize_params, 
                       indent_by, to_rust_type, rnd_arg_val_for_type, extract_parts, mb_type_params_s,
-                      hub_type_params_s, method_media_params)
+                      hub_type_params_s, method_media_params, enclose_in)
 
     def get_parts(part_prop):
         if not part_prop:
@@ -215,7 +215,7 @@ ${capture(util.test_prelude) | hide_rust_doc_test}\
 # use ${util.library_name()}::${request_value.id};
 % endif
 % if media_params:
-# use std::fs::File;
+# use std::fs;
 % endif
 <%block filter="rust_test_fn_invisible">\
 ${capture(lib.test_hub, hub_type_name, comments=False) | hide_rust_doc_test}
@@ -299,10 +299,14 @@ ${'.' + action_name | indent_by(13)}(${action_args});
     }
 
     % for p in media_params:
-    <% 
+<% 
         none_type = 'None::<(' + p.type.default + ', u64, mime::Mime)>' 
-    %>\
-    /// ${p.description}
+%>\
+    ${p.description | rust_doc_comment, indent_all_but_first_by(1)}
+    ///
+    % 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}<${p.type.param}>(mut self, ${p.type.arg_name}: ${p.type.param}, size: u64, mime_type: mime::Mime) -> ${rtype}
                 where ${p.type.param}: ${p.type.where} {
         self.${api.terms.action}(\

src/mako/lib/util.py

@@ -50,20 +50,25 @@ PROTOCOL_TYPE_INFO = {
     'simple' : {
         'arg_name': 'stream',
         'param': 'R',
-        'description': 'TODO: FOO',
-        'default': 'File',
+        'description': """Upload media all at once.
+If the upload fails for whichever reason, all progress is lost.""",
+        'default': 'fs::File',
         'where': 'Read',
         'suffix': '',
-        'example_value': 'File::open("filepath.ext").unwrap(), 148, "application/octet-stream".parse().unwrap()'
+        'example_value': 'fs::File::open("filepath.ext").unwrap(), 148, "application/octet-stream".parse().unwrap()'
     },
     'resumable' : {
         'arg_name': 'resumeable_stream',
         'param': 'RS',
-        'description': 'TODO: BAR',
-        'default': 'File',
+        'description': """Upload media in a resumeable fashion.
+Even if the upload fails or is interrupted, it can be resumed for a 
+certain amount of time as the server maintains state temporarily.
+
+TODO: Write more about how delegation works in this particular case.""",
+        'default': 'fs::File',
         'where': 'ReadSeek',
         'suffix': '_resumable',
-        'example_value': 'File::open("filepath.ext").unwrap(), 282, "application/octet-stream".parse().unwrap()'
+        'example_value': 'fs::File::open("filepath.ext").unwrap(), 282, "application/octet-stream".parse().unwrap()'
     }
 }
 
@@ -464,7 +469,7 @@ def method_media_params(m):
     res = list()
     for pn, proto in mu.protocols.iteritems():
         # the pi (proto-info) dict can be shown to the user
-        pi = {'multipart': proto.multipart, 'maxSize': mu.maxSize, 'mimeTypes': mu.accept}
+        pi = {'multipart': proto.multipart and 'yes' or 'no', 'maxSize': mu.maxSize, 'validMimeTypes': mu.accept}
         try:
             ti = type(m)(PROTOCOL_TYPE_INFO[pn])
         except KeyError: