docs(CLI): optional paramters

Added documentation for flags setting all kinds of optional parameters.

src/mako/api/lib/mbuild.mako

@@ -10,7 +10,8 @@
                       CALL_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, ADD_PARAM_FN, ADD_PARAM_MEDIA_EXAMPLE, upload_action_fn, METHODS_RESOURCE,
-                      method_name_to_variant, unique_type_name, size_to_bytes, method_default_scope)
+                      method_name_to_variant, unique_type_name, size_to_bytes, method_default_scope,
+                      is_repeated_property)
 
     def get_parts(part_prop):
         if not part_prop:
@@ -27,9 +28,6 @@
         part_desc = part_desc[:-1]
         return part_desc
 
-    def is_repeated_property(p):
-        return p.get('repeated', False)
-
     def setter_fn_name(p):
         fn_name = p.name
         if is_repeated_property(p):
@@ -209,20 +207,26 @@ ${self._setter_fn(resource, method, m, p, part_prop, ThisType, c)}\
         part_desc = make_parts_desc(part_prop)
     # end part description
 %>\
+    % if 'description' in p:
+    ${p.description | rust_doc_comment, indent_all_but_first_by(1)}
+    % endif
     % if is_repeated_property(p):
+    ///
     /// Append the given value to the *${split_camelcase_s(p.name)}* ${get_word(p, 'location')}property.
     /// Each appended value will retain its original ordering and be '/'-separated in the URL's parameters.
     % else:
+    ///
     /// Sets the *${split_camelcase_s(p.name)}* ${get_word(p, 'location')}property to the given value.
     % endif
-    ///
     % if show_part_info(m, p):
+    ///
     /// Even though the *parts* list is automatically derived from *Resource* passed in 
     /// during instantiation and indicates which values you are passing, the response would contain the very same parts.
     /// This may not always be desirable, as you can obtain (newly generated) parts you cannot pass in,
     /// like statistics that are generated server side. Therefore you should use this method to specify 
     /// the parts you provide in addition to the ones you want in the response.
     % elif is_required_property(p):
+    ///
     /// Even though the property as already been set when instantiating this call, 
     /// we provide this method for API completeness.
     % endif
@@ -230,10 +234,6 @@ ${self._setter_fn(resource, method, m, p, part_prop, ThisType, c)}\
     ///
     ${part_desc | rust_doc_comment, indent_all_but_first_by(1)}
     % endif
-    /// 
-    % if 'description' in p:
-    ${p.description | rust_doc_comment, indent_all_but_first_by(1)}
-    % endif
     pub fn ${mangle_ident(setter_fn_name(p))}(mut self, ${value_name}: ${InType}) -> ${ThisType} {
         % if p.get('repeated', False):
         self.${property(p.name)}.push(${new_value_copied});

src/mako/cli/docs/commands.md.mako

@@ -1,9 +1,12 @@
 <%namespace name="util" file="../../lib/util.mako"/>\
-<%
-    from util import (hash_comment, new_context, method_default_scope, indent_all_but_first_by)
+<%!
+    from util import (hash_comment, new_context, method_default_scope, indent_all_but_first_by, is_repeated_property)
     from cli import (subcommand_md_filename, new_method_context, SPLIT_START, SPLIT_END, pretty, SCOPE_FLAG,
-                     mangle_subcommand, is_request_value_property, FIELD_SEP)
+                     mangle_subcommand, is_request_value_property, FIELD_SEP, PARAM_FLAG)
 
+    from copy import deepcopy
+%>\
+<%
     c = new_context(schemas, resources, context.get('methods'))
 %>\
 % for resource in sorted(c.rta_map.keys()):
@@ -34,6 +37,7 @@ You can set the scope for this method like this: `${util.program_name()} --${SCO
 % endif # have method scopes
 <%
     rprops = [p for p in mc.required_props if not is_request_value_property(mc, p)]
+    oprops = [p for p in mc.optional_props if not p.get('skip_example', False)]
 %>\
 % if rprops:
 # Required Scalar ${len(rprops) > 1 and 'Arguments' or 'Argument'}
@@ -72,6 +76,33 @@ can be set completely with the following arguments. Note how the cursor position
 * You can also set nested fields without setting the cursor explicitly. For example, to set the mapping from the root, you would specify `-r struct${FIELD_SEP}sub_struct${FIELD_SEP}mapping=foo=bar`. In case the cursor is not at the root, you may explicitly drill down from the root using a leading '${FIELD_SEP}' character.
 
 % endif # have request value
+% if oprops:
+# Optional Method Properties
+
+You may set the following properties to further configure the call.
+
+% for p in sorted(oprops):
+${self._md_property(p)}
+% endfor 
+% endif # optional method properties
+% if parameters is not UNDEFINED:
+# Optional General Properties
+
+The following properties can configure any call, and are not specific to this method.
+
+% for pn in sorted(parameters.keys()):
+<% 
+    p = deepcopy(parameters[pn])
+    p.name = pn
+%>\
+${self._md_property(p)}
+% endfor 
+% endif # general parameters
 ${SPLIT_END}
 % endfor # each method
 % endfor # each resource
+
+<%def name="_md_property(p)">\
+* **-${PARAM_FLAG} ${mangle_subcommand(p.name)}=${p.type}**
+    - ${p.get('description') or "No description provided" | indent_all_but_first_by(2)}
+</%def>

src/mako/lib/util.py

@@ -548,6 +548,9 @@ def schema_doc_format(s):
 def is_required_property(p):
     return p.get('required', False) or p.get('priority', 0) > 0
 
+def is_repeated_property(p):
+    return p.get('repeated', False)
+
 # method_params(...), request_value|None -> (required_properties, optional_properties, part_prop|None)
 def organize_params(params, request_value):
     part_prop = None