From 27b92047854d47465b7efeef8f1bc6f8922ba91c Mon Sep 17 00:00:00 2001
From: Todd Gamblin <tgamblin@llnl.gov>
Date: Fri, 22 Feb 2013 00:20:24 -0800
Subject: [PATCH] Better spack -h: added cmd descriptions.

- each cmd has a desscription attribute that is used for the help strign in argparse.
---
 bin/spack                        | 11 +++++++----
 lib/spack/spack/cmd/__init__.py  | 13 ++++++++++---
 lib/spack/spack/cmd/clean.py     |  2 ++
 lib/spack/spack/cmd/create.py    |  2 ++
 lib/spack/spack/cmd/edit.py      |  1 +
 lib/spack/spack/cmd/fetch.py     |  2 ++
 lib/spack/spack/cmd/graph.py     |  1 +
 lib/spack/spack/cmd/help.py      |  2 ++
 lib/spack/spack/cmd/install.py   |  2 ++
 lib/spack/spack/cmd/list.py      |  1 +
 lib/spack/spack/cmd/purge.py     |  2 ++
 lib/spack/spack/cmd/stage.py     |  2 ++
 lib/spack/spack/cmd/uninstall.py |  2 ++
 13 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/bin/spack b/bin/spack
index 03cc802b8c..13312a69d6 100755
--- a/bin/spack
+++ b/bin/spack
@@ -19,9 +19,12 @@ import spack
 # Command parsing
 parser = argparse.ArgumentParser(
     description='Spack: the Supercomputing PACKage Manager.')
-parser.add_argument('-V', '--version', action='version', version="%s" % spack.spack_version)
-parser.add_argument('-v', '--verbose', action='store_true', dest='verbose')
-parser.add_argument('-d', '--debug', action='store_true', dest='debug')
+parser.add_argument('-V', '--version', action='version',
+                    version="%s" % spack.spack_version)
+parser.add_argument('-v', '--verbose', action='store_true', dest='verbose',
+                    help="print additional output during builds")
+parser.add_argument('-d', '--debug', action='store_true', dest='debug',
+                    help="write out debug logs during compile")
 
 # each command module implements a parser() function, to which we pass its
 # subparser for setup.
@@ -29,8 +32,8 @@ subparsers = parser.add_subparsers(title="subcommands", dest="command")
 
 import spack.cmd
 for cmd in spack.cmd.commands:
-    subparser = subparsers.add_parser(cmd)
     module = spack.cmd.get_module(cmd)
+    subparser = subparsers.add_parser(cmd, help=module.description)
     module.setup_parser(subparser)
 args = parser.parse_args()
 
diff --git a/lib/spack/spack/cmd/__init__.py b/lib/spack/spack/cmd/__init__.py
index 8d2f263b63..a54ade741e 100644
--- a/lib/spack/spack/cmd/__init__.py
+++ b/lib/spack/spack/cmd/__init__.py
@@ -3,11 +3,14 @@
 
 import spack
 import spack.tty as tty
+import spack.attr as attr
 
 # Patterns to ignore in the commands directory when looking for commands.
 ignore_files = r'^\.|^__init__.py$|^#'
 
-setup_parser = "setup_parser"
+SETUP_PARSER = "setup_parser"
+DESCRIPTION  = "description"
+
 command_path = os.path.join(spack.lib_path, "spack", "cmd")
 
 commands = []
@@ -25,8 +28,12 @@ def null_op(*args):
 def get_module(name):
     """Imports the module for a particular command name and returns it."""
     module_name = "%s.%s" % (__name__, name)
-    module = __import__(module_name, fromlist=[name, setup_parser], level=0)
-    module.setup_parser = getattr(module, setup_parser, null_op)
+    module = __import__(
+        module_name, fromlist=[name, SETUP_PARSER, DESCRIPTION],
+        level=0)
+
+    attr.setdefault(module, SETUP_PARSER, null_op)
+    attr.setdefault(module, DESCRIPTION, "")
 
     if not hasattr(module, name):
         tty.die("Command module %s (%s) must define function '%s'."
diff --git a/lib/spack/spack/cmd/clean.py b/lib/spack/spack/cmd/clean.py
index 09922887ca..33f1d68a46 100644
--- a/lib/spack/spack/cmd/clean.py
+++ b/lib/spack/spack/cmd/clean.py
@@ -2,6 +2,8 @@
 import spack.tty as tty
 import spack.stage as stage
 
+description = "Remove staged files for packages"
+
 def setup_parser(subparser):
     subparser.add_argument('names', nargs='+', help="name(s) of package(s) to clean")
     subparser.add_argument('-c', "--clean", action="store_true", dest='clean',
diff --git a/lib/spack/spack/cmd/create.py b/lib/spack/spack/cmd/create.py
index 0997c4a53f..36b6d0e571 100644
--- a/lib/spack/spack/cmd/create.py
+++ b/lib/spack/spack/cmd/create.py
@@ -9,6 +9,8 @@
 from spack.stage import Stage
 from contextlib import closing
 
+description = "Create a new package file from an archive URL"
+
 package_template = string.Template("""\
 from spack import *
 
diff --git a/lib/spack/spack/cmd/edit.py b/lib/spack/spack/cmd/edit.py
index aa279ca295..e9e781ecd6 100644
--- a/lib/spack/spack/cmd/edit.py
+++ b/lib/spack/spack/cmd/edit.py
@@ -3,6 +3,7 @@
 import spack.packages as packages
 import spack.tty as tty
 
+description = "Open package files in $EDITOR"
 
 def setup_parser(subparser):
     subparser.add_argument(
diff --git a/lib/spack/spack/cmd/fetch.py b/lib/spack/spack/cmd/fetch.py
index c53fce6f6f..c447435862 100644
--- a/lib/spack/spack/cmd/fetch.py
+++ b/lib/spack/spack/cmd/fetch.py
@@ -1,5 +1,7 @@
 import spack.packages as packages
 
+description = "Fetch archives for packages"
+
 def setup_parser(subparser):
     subparser.add_argument('name', help="name of package to fetch")
     subparser.add_argument('-f', '--file', dest='file', default=None,
diff --git a/lib/spack/spack/cmd/graph.py b/lib/spack/spack/cmd/graph.py
index 3c16a825a7..2cf08870d2 100644
--- a/lib/spack/spack/cmd/graph.py
+++ b/lib/spack/spack/cmd/graph.py
@@ -1,6 +1,7 @@
 import spack
 import spack.packages as packages
 
+description = "Write out inter-package dependencies in dot graph format"
 
 def graph(parser, args):
     packages.graph_dependencies()
diff --git a/lib/spack/spack/cmd/help.py b/lib/spack/spack/cmd/help.py
index a2b61a2bc9..c90fc50ace 100644
--- a/lib/spack/spack/cmd/help.py
+++ b/lib/spack/spack/cmd/help.py
@@ -1,5 +1,7 @@
 import sys
 
+description = "Get help on spack and its commands"
+
 def setup_parser(subparser):
     subparser.add_argument('help_command', nargs='?', default=None,
                            help='command to get help on')
diff --git a/lib/spack/spack/cmd/install.py b/lib/spack/spack/cmd/install.py
index 14bae90147..9494838832 100644
--- a/lib/spack/spack/cmd/install.py
+++ b/lib/spack/spack/cmd/install.py
@@ -1,6 +1,8 @@
 import spack
 import spack.packages as packages
 
+description = "Build and install packages"
+
 def setup_parser(subparser):
     subparser.add_argument('names', nargs='+', help="name(s) of package(s) to install")
     subparser.add_argument('-i', '--ignore-dependencies',
diff --git a/lib/spack/spack/cmd/list.py b/lib/spack/spack/cmd/list.py
index 2746946ddf..f4f36220c6 100644
--- a/lib/spack/spack/cmd/list.py
+++ b/lib/spack/spack/cmd/list.py
@@ -2,6 +2,7 @@
 import spack.packages as packages
 from spack.colify import colify
 
+description ="List spack packages"
 
 def setup_parser(subparser):
     subparser.add_argument('-i', '--installed', action='store_true', dest='installed',
diff --git a/lib/spack/spack/cmd/purge.py b/lib/spack/spack/cmd/purge.py
index 99f1b98c23..3fc5e583d4 100644
--- a/lib/spack/spack/cmd/purge.py
+++ b/lib/spack/spack/cmd/purge.py
@@ -1,4 +1,6 @@
 import spack.stage as stage
 
+description = "Remove all temporary build files and downloaded archives"
+
 def purge(parser, args):
     stage.purge()
diff --git a/lib/spack/spack/cmd/stage.py b/lib/spack/spack/cmd/stage.py
index 0d7ba23d4b..ad12955b41 100644
--- a/lib/spack/spack/cmd/stage.py
+++ b/lib/spack/spack/cmd/stage.py
@@ -1,5 +1,7 @@
 import spack.packages as packages
 
+description="Expand downloaded archive in preparation for install"
+
 def setup_parser(subparser):
     subparser.add_argument('name', help="name of package to stage")
 
diff --git a/lib/spack/spack/cmd/uninstall.py b/lib/spack/spack/cmd/uninstall.py
index 96b3c45bc5..2cc5aeb2c8 100644
--- a/lib/spack/spack/cmd/uninstall.py
+++ b/lib/spack/spack/cmd/uninstall.py
@@ -1,5 +1,7 @@
 import spack.packages as packages
 
+description="Remove an installed package"
+
 def setup_parser(subparser):
     subparser.add_argument('names', nargs='+', help="name(s) of package(s) to uninstall")
     subparser.add_argument('-f', '--force', action='store_true', dest='force',