Improve command descriptions in --help

Make sure all commands have one line of description, and reduce the
size of some which had large amounts of text.

5 files changed, 31 insertions, 47 deletions

diff --git a/morphlib/plugins/branch_and_merge_plugin.py b/morphlib/plugins/branch_and_merge_plugin.py
index 2c5d1847..1646356d 100644
--- a/morphlib/plugins/branch_and_merge_plugin.py
+++ b/morphlib/plugins/branch_and_merge_plugin.py
@@ -54,7 +54,7 @@ class BranchAndMergePlugin(cliapp.Plugin):
 
         # Advanced commands
         self.app.add_subcommand('foreach', self.foreach,
-                                arg_synopsis='COMMAND')
+                                arg_synopsis='-- COMMAND')
 
         # Plumbing commands (FIXME: should be hidden from --help by default)
         self.app.add_subcommand('workspace', self.workspace,
@@ -505,7 +505,7 @@ class BranchAndMergePlugin(cliapp.Plugin):
         self.app.status(msg='Initialized morph workspace', chatty=True)
 
     def branch(self, args):
-        '''Branch the whole system.'''
+        '''Create a new system branch.'''
 
         if len(args) not in [2, 3]:
             raise cliapp.AppException('morph branch needs name of branch '
@@ -714,19 +714,18 @@ class BranchAndMergePlugin(cliapp.Plugin):
                              'been comitted')
 
     def petrify(self, args):
-        '''Convert all chunk refs in a branch to be fixed SHA1s
-
-        This allows the developer to work on a feature in isolation, without
-        changes from upstream breaking the world under their feet.
-
-        Strata refs are not petrified, because they must all be edited to set
-        the new chunk refs, which requires branching them all for the current
-        branch - so they will not be updated outside of the user's control in
-        any case. Chunks that have already been edited on the current branch
-        are also not petrified.
+        '''Convert all chunk refs in a system branch to be fixed SHA1s
 
+        This isolates the branch from changes made by other developers in the
+        chunk repositories.
         '''
 
+        # Stratum refs are not petrified, because they must all be edited to
+        # set the new chunk refs, which requires branching them all for the
+        # current branch - so they will not be updated outside of the user's
+        # control in any case. Chunks that have already been edited on the
+        # current branch are also not petrified.
+
         if len(args) != 0:
             raise cliapp.AppException('morph petrify takes no arguments')
 
@@ -786,16 +785,10 @@ class BranchAndMergePlugin(cliapp.Plugin):
                              'been comitted')
 
     def unpetrify(self, args):
-        '''Reverse the process of petrification
-
-        Unpetrifies all chunk refs in a branch that were previously petrified.
-        Makes no attempt to 'unedit' strata that were branched solely so they
-        could be petrified.
-
-        If a branch is petrified and then branched from, the child branch can
-        be unpetrified independently of the parent.
+        '''Reverse the process of petrification'''
 
-        '''
+        # This function makes no attempt to 'unedit' strata that were branched
+        # solely so they could be petrified.
 
         if len(args) != 0:
             raise cliapp.AppException('morph unpetrify takes no arguments')
@@ -1115,6 +1108,8 @@ class BranchAndMergePlugin(cliapp.Plugin):
             raise
 
     def build(self, args):
+        '''Build a system from the current system branch'''
+
         if len(args) != 1:
             raise cliapp.AppException('morph build expects exactly one '
                                       'parameter: the system to build')
@@ -1334,6 +1329,7 @@ class BranchAndMergePlugin(cliapp.Plugin):
                              ':%s' % info['build-ref']], cwd=info['dirname'])
 
     def status(self, args):
+        '''Show information about the current system branch or workspace'''
         if len(args) != 0:
             raise cliapp.AppException('morph status takes no arguments')
 
@@ -1379,16 +1375,14 @@ class BranchAndMergePlugin(cliapp.Plugin):
     def foreach(self, args):
         '''Run a command in each repository checked out in a system branch
 
-        For simplicity, this simply iterates repositories in the directory
-        rather than walking through the morphologies as 'morph merge' does.
-
-        Morph will interpret switch arguments, so you should separate the
-        command with --, as in the following example:
-
-            morph foreach -- git status --short
+        Use -- before specifying the command to separate its arguments from
+        Morph's own arguments.
 
         '''
 
+        # For simplicity, this simply iterates repositories in the directory
+        # rather than walking through the morphologies as 'morph merge' does.
+
         if len(args) == 0:
             raise cliapp.AppException('morph foreach expects a command to run')
 
@@ -1416,18 +1410,18 @@ class BranchAndMergePlugin(cliapp.Plugin):
                     'Command failed at repo %s: %s' % (repo, ' '.join(args)))
 
     def workspace(self, args):
-        '''Find morph workspace directory from current working directory.'''
+        '''Find the toplevel directory of the current workspace'''
 
         self.app.output.write('%s\n' % self.deduce_workspace())
 
     def show_system_branch(self, args):
-        '''Print name of current system branch.'''
+        '''Print name of current system branch'''
 
         branch, dirname = self.deduce_system_branch()
         self.app.output.write('%s\n' % branch)
 
     def show_branch_root(self, args):
-        '''Print name of the repository that was branched off from.'''
+        '''Print name of the repository holding the system morphologies'''
 
         workspace = self.deduce_workspace()
         system_branch, branch_dir = self.deduce_system_branch()
diff --git a/morphlib/plugins/build_plugin.py b/morphlib/plugins/build_plugin.py
index 7cc2d6ec..6583a6a8 100644
--- a/morphlib/plugins/build_plugin.py
+++ b/morphlib/plugins/build_plugin.py
@@ -29,15 +29,10 @@ class BuildPlugin(cliapp.Plugin):
         pass
 
     def build_morphology(self, args):
-        '''Build a binary from a morphology.
+        '''Build a system, outside of a system branch
 
-        Command line arguments are the repository, git tree-ish reference,
-        and morphology filename. Morph takes care of building all dependencies
-        before building the morphology. All generated binaries are put into the
-        cache.
-
-        (The triplet of command line arguments may be repeated as many
-        times as necessary.)
+        Command line arguments are the repository, git ref,
+        and morphology filename.
 
         '''
 
diff --git a/morphlib/plugins/graphing_plugin.py b/morphlib/plugins/graphing_plugin.py
index 3594e9b9..c719f6e4 100644
--- a/morphlib/plugins/graphing_plugin.py
+++ b/morphlib/plugins/graphing_plugin.py
@@ -31,6 +31,7 @@ class GraphingPlugin(cliapp.Plugin):
         pass
 
     def graph_build_depends(self, args):
+        '''Create a visualisation of build dependencies in a stratum'''
         for repo_name, ref, filename in self.app.itertriplets(args):
             self.app.status(msg='Creating build order for '
                                 '%(repo_name)s %(ref)s %(filename)s',
diff --git a/morphlib/plugins/show_dependencies_plugin.py b/morphlib/plugins/show_dependencies_plugin.py
index dee84c59..13ec512a 100644
--- a/morphlib/plugins/show_dependencies_plugin.py
+++ b/morphlib/plugins/show_dependencies_plugin.py
@@ -31,7 +31,7 @@ class ShowDependenciesPlugin(cliapp.Plugin):
         pass
 
     def show_dependencies(self, args):
-        '''Dumps the dependency tree of all input morphologies.'''
+        '''Dumps the dependency tree of all input morphologies'''
 
         if not os.path.exists(self.app.settings['cachedir']):
             os.mkdir(self.app.settings['cachedir'])
diff --git a/morphlib/plugins/update_gits_plugin.py b/morphlib/plugins/update_gits_plugin.py
index 608b34f1..083439f5 100644
--- a/morphlib/plugins/update_gits_plugin.py
+++ b/morphlib/plugins/update_gits_plugin.py
@@ -31,13 +31,7 @@ class UpdateGitsPlugin(cliapp.Plugin):
         pass
 
     def update_gits(self, args):
-        '''Update cached git repositories.
-
-        Parse the given morphologies, and their dependencies, and
-        update all the git repositories referred to by them in the
-        morph cache directory.
-
-        '''
+        '''Manually update cached git repositories for the given morphology'''
 
         app = self.app
         if not os.path.exists(app.settings['cachedir']):