[recipes.py] add missing helpstrings, merge test subcommands into main parser.

recipes.py

 #!/usr/bin/env python
 # Copyright 2015 The LUCI Authors. All rights reserved.
 # Use of this source code is governed under the Apache License, Version 2.0
 # that can be found in the LICENSE file.
 
 """Tool to interact with recipe repositories.
 
 This tool operates on the nearest ancestor directory containing an
 infra/config/recipes.cfg.
 """
@@ skipping 19 matching lines @@
 
 import argparse  # this is vendored
 from recipe_engine import arguments_pb2
 from google.protobuf import json_format as jsonpb
 
 
 from recipe_engine import fetch, lint_test, bundle, depgraph, autoroll
 from recipe_engine import remote, refs, doc, test, run
 
 
+# Each of these subcommands has a method:
+#
+#   def add_subparsers(argparse._SubParsersAction): ...
+#
+# which is expected to add a subparser by calling .add_parser on it. In
+# addition, the add_subparsers method should call .set_defaults on the created
+# sub-parser, and set the following values:
+#   func (fn(package_deps, args)) - The function called if the sub command is
+#     invoked.
+#   postprocess_func (fn(parser, args)) - A validation/normalization function
+#     which is called if the sub command is invoked. This function can
+#     check/adjust the parsed args, calling parser.error if a problem is
+#     encountered. This function is optional.
+#   bare_command (bool) - This sub command's func will be called before parsing
+#     package_deps. This is only used for the `remote` subcommand. See the
+#     comment in add_common_args for why.
+#
+# Example:
+#
+#   def add_subparsers(parser):
+#     sub = parser.add_parser("subcommand", help="a cool subcommand")
+#     sub.add_argument("--cool_arg", help="it's gotta be cool")
+#
+#     def postprocess_args(parser, args):
+#       if "cool" not in args.cool_arg:
+#         parser.error("your cool_arg is not cool!")
+#
+#     sub.set_defaults(func=main)
+#
+#   def main(package_deps, args):
+#     print args.cool_arg
 _SUBCOMMANDS = [
+  run,
+  test,
+
   autoroll,
   bundle,
   depgraph,
   doc,
   fetch,
   lint_test,
   refs,
   remote,
-  run,
-  test,
 ]
 
 
 def add_common_args(parser):
   from recipe_engine import package_io
 
   class ProjectOverrideAction(argparse.Action):
     def __call__(self, parser, namespace, values, option_string=None):
       p = values.split('=', 2)
       if len(p) != 2:
@@ skipping 82 matching lines @@
         parser.error('%s forbids --package' % args.command)
     else:
       if not args.package:
         parser.error('%s requires --package' % args.command)
 
   return post_process_args
 
 
 def main():
   parser = argparse.ArgumentParser(
-      description='Interact with the recipe system.')
+    description='Interact with the recipe system.')
 
   common_postprocess_func = add_common_args(parser)
 
   subp = parser.add_subparsers()
   for module in _SUBCOMMANDS:
     module.add_subparser(subp)
 
   args = parser.parse_args()
   common_postprocess_func(parser, args)
   args.postprocess_func(parser, args)
@@ skipping 77 matching lines @@
 
   if not isinstance(ret, int):
     if ret is None:
       ret = 0
     else:
       print >> sys.stderr, ret
       ret = 1
   sys.stdout.flush()
   sys.stderr.flush()
   os._exit(ret)