From 265ca582f02c5cf107c677051c65d43534aaddbb Mon Sep 17 00:00:00 2001
From: Steve Martinelli <stevemar@ca.ibm.com>
Date: Mon, 5 Jan 2015 01:53:46 -0500
Subject: [PATCH] Command docs: volume

Change-Id: Id1e500d5fb19ffdeb0d1bde9e22c3143c0873d0c
---
 doc/source/command-objects/volume.rst | 189 ++++++++++++++++++++++++++
 doc/source/commands.rst               |   2 +-
 openstackclient/volume/v1/volume.py   |  45 +++---
 3 files changed, 213 insertions(+), 23 deletions(-)
 create mode 100644 doc/source/command-objects/volume.rst

diff --git a/doc/source/command-objects/volume.rst b/doc/source/command-objects/volume.rst
new file mode 100644
index 0000000000..2eec2d7b25
--- /dev/null
+++ b/doc/source/command-objects/volume.rst
@@ -0,0 +1,189 @@
+======
+volume
+======
+
+Volume v1
+
+volume create
+-------------
+
+Create new volume
+
+.. program:: volume create
+.. code:: bash
+
+    os volume create
+        --size <size>
+        [--snapshot-id <snapshot-id>]
+        [--description <description>]
+        [--type <volume-type>]
+        [--user <user>]
+        [--project <project>]
+        [--availability-zone <availability-zone>]
+        [--image <image>]
+        [--source <volume>]
+        [--property <key=value> [...] ]
+        <name>
+
+.. option:: --size <size> (required)
+
+    New volume size in GB
+
+.. option:: --snapshot-id <snapshot-id>
+
+    Use <snapshot-id> as source of new volume
+
+.. option:: --description <description>
+
+    New volume description
+
+.. option:: --type <volume-type>
+
+    Use <volume-type> as the new volume type
+
+.. option:: --user <user>
+
+    Specify an alternate user (name or ID)
+
+.. option:: --project <project>
+
+    Specify an alternate project (name or ID)
+
+.. option:: --availability-zone <availability-zone>
+
+    Create new volume in <availability-zone>
+
+.. option:: --image <image>
+
+    Use <image> as source of new volume (name or ID)
+
+.. option:: --source <source>
+
+    Volume to clone (name or ID)
+
+.. option:: --property <key=value>
+
+    Set a property on this volume (repeat option to set multiple properties)
+
+.. describe:: <name>
+
+    New volume name
+
+The :option:`--project` and :option:`--user`  options are typically only
+useful for admin users, but may be allowed for other users depending on
+the policy of the cloud and the roles granted to the user.
+
+volume delete
+-------------
+
+Delete volume(s)
+
+.. program:: volume delete
+.. code:: bash
+
+    os volume delete
+        [--force]
+         <volume> [<volume> ...]
+
+.. option:: --force
+
+    Attempt forced removal of volume(s), regardless of state (defaults to False)
+
+.. describe:: <volume>
+
+    Volume(s) to delete (name or ID)
+
+volume list
+-----------
+
+List volumes
+
+.. program:: volume list
+.. code:: bash
+
+    os volume list
+        [--status <status>]
+        [--name <name>]
+        [--all-projects]
+        [--long]
+
+.. option:: --status <status>
+
+    Filter results by status
+
+.. option:: --name <name>
+
+    Filter results by name
+
+.. option:: --all-projects
+
+    Include all projects (admin only)
+
+.. option:: --long
+
+    List additional fields in output
+
+volume set
+----------
+
+Set volume properties
+
+.. program:: volume set
+.. code:: bash
+
+    os volume set
+        [--name <name>]
+        [--description <description>]
+        [--property <key=value> [...] ]
+        <volume>
+
+.. option:: --name <name>
+
+    New volume name
+
+.. option:: --description <description>
+
+    New volume description
+
+.. option:: --property <key=value>
+
+    Property to add or modify for this volume (repeat option to set multiple properties)
+
+.. describe:: <volume>
+
+    Volume to modify (name or ID)
+
+volume show
+-----------
+
+Show volume details
+
+.. program:: volume show
+.. code:: bash
+
+    os volume show
+        <volume>
+
+.. describe:: <volume>
+
+    Volume to display (name or ID)
+
+volume unset
+------------
+
+Unset volume properties
+
+.. program:: volume unset
+.. code:: bash
+
+    os volume unset
+        [--property <key>]
+        <volume>
+
+.. option:: --property <key>
+
+    Property to remove from volume (repeat option to remove multiple properties)
+
+.. describe:: <volume>
+
+    Volume to modify (name or ID)
diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index 5bec1a8518..f5f6d01513 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -112,7 +112,7 @@ referring to both Compute and Volume quotas.
 * ``usage``: (**Compute**) display host resources being consumed
 * ``user``: (**Identity**) individual cloud resources users
 * ``user role``: (**Identity**) roles assigned to a user
-* ``volume``: Volume - block volumes
+* ``volume``: (**Volume**) block volumes
 * ``volume type``: (**Volume**) deployment-specific types of volumes available
 
 Actions
diff --git a/openstackclient/volume/v1/volume.py b/openstackclient/volume/v1/volume.py
index d82f6b4b76..e59331fad3 100644
--- a/openstackclient/volume/v1/volume.py
+++ b/openstackclient/volume/v1/volume.py
@@ -36,14 +36,14 @@ class CreateVolume(show.ShowOne):
         parser.add_argument(
             'name',
             metavar='<name>',
-            help='Name of the new volume',
+            help='New volume name',
         )
         parser.add_argument(
             '--size',
             metavar='<size>',
             required=True,
             type=int,
-            help='New volume size',
+            help='New volume size in GB',
         )
         parser.add_argument(
             '--snapshot-id',
@@ -53,45 +53,45 @@ class CreateVolume(show.ShowOne):
         parser.add_argument(
             '--description',
             metavar='<description>',
-            help='Description of the volume',
+            help='New volume description',
         )
         parser.add_argument(
             '--type',
             metavar='<volume-type>',
-            help='Type of volume',
+            help='Use <volume-type> as the new volume type',
         )
         parser.add_argument(
             '--user',
             metavar='<user>',
-            help='Specify a different user (admin only)',
+            help='Specify an alternate user (name or ID)',
         )
         parser.add_argument(
             '--project',
             metavar='<project>',
-            help='Specify a different project (admin only)',
+            help='Specify an alternate project (name or ID)',
         )
         parser.add_argument(
             '--availability-zone',
             metavar='<availability-zone>',
             help='Create new volume in <availability-zone>',
         )
-        parser.add_argument(
-            '--property',
-            metavar='<key=value>',
-            action=parseractions.KeyValueAction,
-            help='Property to store for this volume '
-                 '(repeat option to set multiple properties)',
-        )
         parser.add_argument(
             '--image',
             metavar='<image>',
-            help='Use <image> as source of new volume',
+            help='Use <image> as source of new volume (name or ID)',
         )
         parser.add_argument(
             '--source',
             metavar='<volume>',
             help='Volume to clone (name or ID)',
         )
+        parser.add_argument(
+            '--property',
+            metavar='<key=value>',
+            action=parseractions.KeyValueAction,
+            help='Set a property on this volume '
+                 '(repeat option to set multiple properties)',
+        )
 
         return parser
 
@@ -172,7 +172,8 @@ class DeleteVolume(command.Command):
             dest='force',
             action='store_true',
             default=False,
-            help='Attempt forced removal of volume(s), regardless of state',
+            help='Attempt forced removal of volume(s), regardless of state '
+                 '(defaults to False)',
         )
         return parser
 
@@ -216,7 +217,7 @@ class ListVolume(lister.Lister):
             '--long',
             action='store_true',
             default=False,
-            help='Display properties',
+            help='List additional fields in output',
         )
         return parser
 
@@ -318,19 +319,19 @@ class SetVolume(command.Command):
         )
         parser.add_argument(
             '--name',
-            metavar='<new-name>',
+            metavar='<name>',
             help='New volume name',
         )
         parser.add_argument(
             '--description',
-            metavar='<new-description>',
+            metavar='<description>',
             help='New volume description',
         )
         parser.add_argument(
             '--property',
             metavar='<key=value>',
             action=parseractions.KeyValueAction,
-            help='Property to add/change for this volume '
+            help='Property to add or modify for this volume '
                  '(repeat option to set multiple properties)',
         )
         return parser
@@ -400,15 +401,15 @@ class UnsetVolume(command.Command):
         parser.add_argument(
             'volume',
             metavar='<volume>',
-            help='Volume to change (name or ID)',
+            help='Volume to modify (name or ID)',
         )
         parser.add_argument(
             '--property',
             metavar='<key>',
             action='append',
             default=[],
-            help='Property key to remove from volume '
-                 '(repeat to set multiple values)',
+            help='Property to remove from volume '
+                 '(repeat option to remove multiple properties)',
         )
         return parser