Bug 1439727 - Add a docstring for mach clobber; r=nalexander

This makes `mach help clobber` more useful.

MozReview-Commit-ID: GsIUqhUzVGP

python/mozbuild/mozbuild/mach_commands.py

@@ -341,6 +341,22 @@ class Clobber(MachCommandBase):
     @CommandArgument('--full', action='store_true',
         help='Perform a full clobber')
     def clobber(self, what, full=False):
+        """Clean up the source and object directories.
+
+        Performing builds and running various commands generate various files.
+
+        Sometimes it is necessary to clean up these files in order to make
+        things work again. This command can be used to perform that cleanup.
+
+        By default, this command removes most files in the current object
+        directory (where build output is stored). Some files (like Visual
+        Studio project files) are not removed by default. If you would like
+        to remove the object directory in its entirety, run with `--full`.
+
+        The `python` target will clean up various generated Python files from
+        the source directory. Run this to remove .pyc files, compiled C
+        extensions, etc.
+        """
         invalid = set(what) - set(self.CLOBBER_CHOICES)
         if invalid:
             print('Unknown clobber target(s): {}'.format(', '.join(invalid)))