Merge inbound to central, a=merge

python/mach/mach/base.py

@@ -77,6 +77,9 @@ class MethodHandler(object):
         # Description of the purpose of this command.
         'description',
 
+        # Docstring associated with command.
+        'docstring',
+
         # Functions used to 'skip' commands if they don't meet the conditions
         # in a given context.
         'conditions',
@@ -99,7 +102,7 @@ class MethodHandler(object):
     )
 
     def __init__(self, cls, method, name, category=None, description=None,
-        conditions=None, parser=None, arguments=None,
+        docstring=None, conditions=None, parser=None, arguments=None,
         argument_group_names=None, pass_context=False,
         subcommand_handlers=None):
 
@@ -108,6 +111,7 @@ class MethodHandler(object):
         self.name = name
         self.category = category
         self.description = description
+        self.docstring = docstring
         self.conditions = conditions or []
         self.arguments = arguments or []
         self.argument_group_names = argument_group_names or []

python/mach/mach/decorators.py

@@ -89,7 +89,8 @@ def CommandProvider(cls):
         argument_group_names = getattr(value, '_mach_command_arg_group_names', None)
 
         handler = MethodHandler(cls, attr, command_name, category=category,
-            description=description, conditions=conditions, parser=parser,
+            description=description, docstring=value.__doc__,
+            conditions=conditions, parser=parser,
             arguments=arguments, argument_group_names=argument_group_names,
             pass_context=pass_context)
 
@@ -121,6 +122,7 @@ def CommandProvider(cls):
         argument_group_names = getattr(value, '_mach_command_arg_group_names', None)
 
         handler = MethodHandler(cls, attr, subcommand, description=description,
+            docstring=value.__doc__,
             arguments=arguments, argument_group_names=argument_group_names,
             pass_context=pass_context)
         parent = Registrar.command_handlers[command]

python/mach/mach/dispatcher.py

@@ -351,13 +351,19 @@ class CommandAction(argparse.Action):
 
         self._populate_command_group(c_parser, handler, group)
 
-        # This will print the description of the command below the usage.
-        description = handler.description
-        if description:
-            parser.description = description
+        # Set the long help of the command to the docstring (if present) or
+        # the command decorator description argument (if present).
+        if handler.docstring:
+            parser.description = format_docstring(handler.docstring)
+        elif handler.description:
+            parser.description = handler.description
 
         parser.usage = '%(prog)s [global arguments] ' + command + \
             ' [command arguments]'
+
+        # This is needed to preserve line endings in the description field,
+        # which may be populated from a docstring.
+        parser.formatter_class = argparse.RawDescriptionHelpFormatter
         parser.print_help()
         print('')
         c_parser.print_help()
@@ -371,6 +377,11 @@ class CommandAction(argparse.Action):
             group.add_argument(subcommand, help=subhandler.description,
                 action='store_true')
 
+        if handler.docstring:
+            parser.description = format_docstring(handler.docstring)
+
+        parser.formatter_class = argparse.RawDescriptionHelpFormatter
+
         parser.print_help()
 
     def _handle_subcommand_help(self, parser, command, subcommand, handler):
@@ -382,10 +393,40 @@ class CommandAction(argparse.Action):
         group = c_parser.add_argument_group('Sub Command Arguments')
         self._populate_command_group(c_parser, handler, group)
 
+        if handler.docstring:
+            parser.description = format_docstring(handler.docstring)
+
+        parser.formatter_class = argparse.RawDescriptionHelpFormatter
+
         parser.print_help()
         print('')
         c_parser.print_help()
 
+
 class NoUsageFormatter(argparse.HelpFormatter):
     def _format_usage(self, *args, **kwargs):
         return ""
+
+
+def format_docstring(docstring):
+    """Format a raw docstring into something suitable for presentation.
+
+    This function is based on the example function in PEP-0257.
+    """
+    if not docstring:
+        return ''
+    lines = docstring.expandtabs().splitlines()
+    indent = sys.maxint
+    for line in lines[1:]:
+        stripped = line.lstrip()
+        if stripped:
+            indent = min(indent, len(line) - len(stripped))
+    trimmed = [lines[0].strip()]
+    if indent < sys.maxint:
+        for line in lines[1:]:
+            trimmed.append(line[indent:].rstrip())
+    while trimmed and not trimmed[-1]:
+        trimmed.pop()
+    while trimmed and not trimmed[0]:
+        trimmed.pop(0)
+    return '\n'.join(trimmed)

python/mozbuild/mozbuild/frontend/mach_commands.py

@@ -85,7 +85,11 @@ class MozbuildFileCommands(MachCommandBase):
     @Command('file-info', category='build-dev',
              description='Query for metadata about files.')
     def file_info(self):
-        pass
+        """Show files metadata derived from moz.build files.
+
+        moz.build files contain "Files" sub-contexts for declaring metadata
+        against file patterns. This command suite is used to query that data.
+        """
 
     @SubCommand('file-info', 'bugzilla-component',
                 'Show Bugzilla component info for files listed.')
@@ -94,6 +98,11 @@ class MozbuildFileCommands(MachCommandBase):
     @CommandArgument('paths', nargs='+',
                      help='Paths whose data to query')
     def file_info_bugzilla(self, paths, rev=None):
+        """Show Bugzilla component for a set of files.
+
+        Given a requested set of files (which can be specified using
+        wildcards), print the Bugzilla component for each file.
+        """
         components = defaultdict(set)
         try:
             for p, m in self._get_files_info(paths, rev=rev).items():