From a3a2a7e9f0b59c151c87df3860350df10a48963f Mon Sep 17 00:00:00 2001
From: Dean Troyer <dtroyer@gmail.com>
Date: Mon, 28 Mar 2016 14:02:33 -0500
Subject: [PATCH] Docs cleanup: volume command help

This formats the volume command help text consistent with the rest of OSC,
adds some reference targets and some explanation text to some commands.

No functional changes have been made, only cosmetic/help output.

Change-Id: Ib86ec3ca58bdea5f33078ced3ec3583b2be0e89a
---
 doc/source/command-objects/volume.rst | 92 ++++++++++++++++-----------
 openstackclient/volume/v1/volume.py   | 46 +++++++-------
 openstackclient/volume/v2/volume.py   | 74 ++++++++++-----------
 3 files changed, 115 insertions(+), 97 deletions(-)

diff --git a/doc/source/command-objects/volume.rst b/doc/source/command-objects/volume.rst
index fd32c3278f..a51d1117d1 100644
--- a/doc/source/command-objects/volume.rst
+++ b/doc/source/command-objects/volume.rst
@@ -14,32 +14,45 @@ Create new volume
 
     os volume create
         --size <size>
-        [--snapshot <snapshot>]
-        [--description <description>]
         [--type <volume-type>]
+        [--image <image>]
+        [--snapshot <snapshot>]
+        [--source <volume>]
+        [--description <description>]
         [--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 <snapshot>
-
-    Use <snapshot> as source of new volume
-
-.. option:: --description <description>
-
-    New volume description
+    Volume size in GB
 
 .. option:: --type <volume-type>
 
-    Use <volume-type> as the new volume type
+    Set the type of volume
+
+    Select :option:`\<volume-type\>` from the available types as shown
+    by ``volume type list``.
+
+.. option:: --image <image>
+
+    Use :option:`\<image\>` as source of volume (name or ID)
+
+    This is commonly used to create a boot volume for a server.
+
+.. option:: --snapshot <snapshot>
+
+    Use :option:`\<snapshot\>` as source of volume (name or ID)
+
+.. option:: --source <source>
+
+    Volume to clone (name or ID)
+
+.. option:: --description <description>
+
+    Volume description
 
 .. option:: --user <user>
 
@@ -51,23 +64,16 @@ Create new volume
 
 .. 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)
+    Create volume in :option:`\<availability-zone\>`
 
 .. option:: --property <key=value>
 
     Set a property on this volume (repeat option to set multiple properties)
 
+.. _volume_create-name:
 .. describe:: <name>
 
-    New volume name
+    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
@@ -83,12 +89,13 @@ Delete volume(s)
 
     os volume delete
         [--force]
-         <volume> [<volume> ...]
+        <volume> [<volume> ...]
 
 .. option:: --force
 
     Attempt forced removal of volume(s), regardless of state (defaults to False)
 
+.. _volume_delete-volume:
 .. describe:: <volume>
 
     Volume(s) to delete (name or ID)
@@ -102,35 +109,37 @@ List volumes
 .. code:: bash
 
     os volume list
-        [--all-projects]
         [--project <project> [--project-domain <project-domain>]]
         [--user <user> [--user-domain <user-domain>]]
         [--name <name>]
         [--status <status>]
+        [--all-projects]
         [--long]
 
 .. option:: --project <project>
 
-    Filter results by project (name or ID) (admin only)
+    Filter results by :option:`\<project\>` (name or ID) (admin only)
 
     *Volume version 2 only*
 
 .. option:: --project-domain <project-domain>
 
     Domain the project belongs to (name or ID).
+
     This can be used in case collisions between project names exist.
 
     *Volume version 2 only*
 
 .. option:: --user <user>
 
-    Filter results by user (name or ID) (admin only)
+    Filter results by :option:`\<user\>` (name or ID) (admin only)
 
     *Volume version 2 only*
 
 .. option:: --user-domain <user-domain>
 
     Domain the user belongs to (name or ID).
+
     This can be used in case collisions between user names exist.
 
     *Volume version 2 only*
@@ -161,8 +170,8 @@ Set volume properties
 
     os volume set
         [--name <name>]
-        [--description <description>]
         [--size <size>]
+        [--description <description>]
         [--property <key=value> [...] ]
         [--image-property <key=value> [...] ]
         <volume>
@@ -171,25 +180,30 @@ Set volume properties
 
     New volume name
 
-.. option:: --description <description>
-
-    New volume description
-
 .. option:: --size <size>
 
     Extend volume size in GB
 
+.. option:: --description <description>
+
+    New volume description
+
 .. option:: --property <key=value>
 
-    Property to add or modify for this volume (repeat option to set multiple properties)
+    Set a property on this volume (repeat option to set multiple properties)
 
 .. option:: --image-property <key=value>
 
-    To add or modify image properties for this volume.
+    Set an image property on this volume
     (repeat option to set multiple image properties)
 
+    Image properties are copied along with the image when creating a volume
+    using :option:`--image`.  Note that these properties are immutable on the
+    image itself, this option updates the copy attached to this volume.
+
     *Volume version 2 only*
 
+.. _volume_set-volume:
 .. describe:: <volume>
 
     Volume to modify (name or ID)
@@ -205,6 +219,7 @@ Show volume details
     os volume show
         <volume>
 
+.. _volume_show-volume:
 .. describe:: <volume>
 
     Volume to display (name or ID)
@@ -224,13 +239,16 @@ Unset volume properties
 
 .. option:: --property <key>
 
-    Property to remove from volume (repeat option to remove multiple properties)
+    Remove a property from volume (repeat option to remove multiple properties)
 
 .. option:: --image-property <key>
 
-    To remove image properties from volume
+    Remove an image property from volume
     (repeat option to remove multiple image properties)
 
+    *Volume version 2 only*
+
+.. _volume_unset-volume:
 .. describe:: <volume>
 
     Volume to modify (name or ID)
diff --git a/openstackclient/volume/v1/volume.py b/openstackclient/volume/v1/volume.py
index 90827d2041..29c197ef81 100644
--- a/openstackclient/volume/v1/volume.py
+++ b/openstackclient/volume/v1/volume.py
@@ -31,20 +31,30 @@ class CreateVolume(command.ShowOne):
         parser.add_argument(
             'name',
             metavar='<name>',
-            help='New volume name',
+            help='Volume name',
         )
         parser.add_argument(
             '--size',
             metavar='<size>',
             required=True,
             type=int,
-            help='New volume size in GB',
+            help='Volume size in GB',
+        )
+        parser.add_argument(
+            '--type',
+            metavar='<volume-type>',
+            help="Set the type of volume",
+        )
+        parser.add_argument(
+            '--image',
+            metavar='<image>',
+            help='Use <image> as source of volume (name or ID)',
         )
         snapshot_group = parser.add_mutually_exclusive_group()
         snapshot_group.add_argument(
             '--snapshot',
             metavar='<snapshot>',
-            help='Use <snapshot> as source of new volume',
+            help='Use <snapshot> as source of volume (name or ID)',
         )
         snapshot_group.add_argument(
             '--snapshot-id',
@@ -52,14 +62,14 @@ class CreateVolume(command.ShowOne):
             help=argparse.SUPPRESS,
         )
         parser.add_argument(
-            '--description',
-            metavar='<description>',
-            help='New volume description',
+            '--source',
+            metavar='<volume>',
+            help='Volume to clone (name or ID)',
         )
         parser.add_argument(
-            '--type',
-            metavar='<volume-type>',
-            help='Use <volume-type> as the new volume type',
+            '--description',
+            metavar='<description>',
+            help='Volume description',
         )
         parser.add_argument(
             '--user',
@@ -74,17 +84,7 @@ class CreateVolume(command.ShowOne):
         parser.add_argument(
             '--availability-zone',
             metavar='<availability-zone>',
-            help='Create new volume in <availability-zone>',
-        )
-        parser.add_argument(
-            '--image',
-            metavar='<image>',
-            help='Use <image> as source of new volume (name or ID)',
-        )
-        parser.add_argument(
-            '--source',
-            metavar='<volume>',
-            help='Volume to clone (name or ID)',
+            help='Create volume in <availability-zone>',
         )
         parser.add_argument(
             '--property',
@@ -308,7 +308,7 @@ class SetVolume(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(
             '--name',
@@ -330,7 +330,7 @@ class SetVolume(command.Command):
             '--property',
             metavar='<key=value>',
             action=parseractions.KeyValueAction,
-            help='Property to add or modify for this volume '
+            help='Set a property on this volume '
                  '(repeat option to set multiple properties)',
         )
         return parser
@@ -411,7 +411,7 @@ class UnsetVolume(command.Command):
             metavar='<key>',
             action='append',
             default=[],
-            help='Property to remove from volume '
+            help='Remove a property from volume '
                  '(repeat option to remove multiple properties)',
             required=True,
         )
diff --git a/openstackclient/volume/v2/volume.py b/openstackclient/volume/v2/volume.py
index 5d9d2d9e35..5b7511e8ea 100644
--- a/openstackclient/volume/v2/volume.py
+++ b/openstackclient/volume/v2/volume.py
@@ -32,29 +32,39 @@ class CreateVolume(command.ShowOne):
         parser.add_argument(
             "name",
             metavar="<name>",
-            help="New volume name"
+            help="Volume name",
         )
         parser.add_argument(
             "--size",
             metavar="<size>",
             type=int,
             required=True,
-            help="New volume size in GB"
-        )
-        parser.add_argument(
-            "--snapshot",
-            metavar="<snapshot>",
-            help="Use <snapshot> as source of new volume (name or ID)"
-        )
-        parser.add_argument(
-            "--description",
-            metavar="<description>",
-            help="New volume description"
+            help="Volume size in GB",
         )
         parser.add_argument(
             "--type",
             metavar="<volume-type>",
-            help="Use <volume-type> as the new volume type",
+            help="Set the type of volume",
+        )
+        parser.add_argument(
+            "--image",
+            metavar="<image>",
+            help="Use <image> as source of volume (name or ID)",
+        )
+        parser.add_argument(
+            "--snapshot",
+            metavar="<snapshot>",
+            help="Use <snapshot> as source of volume (name or ID)",
+        )
+        parser.add_argument(
+            "--source",
+            metavar="<volume>",
+            help="Volume to clone (name or ID)",
+        )
+        parser.add_argument(
+            "--description",
+            metavar="<description>",
+            help="Volume description",
         )
         parser.add_argument(
             '--user',
@@ -69,24 +79,14 @@ class CreateVolume(command.ShowOne):
         parser.add_argument(
             "--availability-zone",
             metavar="<availability-zone>",
-            help="Create new volume in <availability_zone>"
-        )
-        parser.add_argument(
-            "--image",
-            metavar="<image>",
-            help="Use <image> as source of new volume (name or ID)"
-        )
-        parser.add_argument(
-            "--source",
-            metavar="<volume>",
-            help="Volume to clone (name or ID)"
+            help="Create volume in <availability-zone>",
         )
         parser.add_argument(
             "--property",
             metavar="<key=value>",
             action=parseractions.KeyValueAction,
             help="Set a property to this volume "
-                 "(repeat option to set multiple properties)"
+                 "(repeat option to set multiple properties)",
         )
         return parser
 
@@ -188,13 +188,13 @@ class ListVolume(command.Lister):
         parser = super(ListVolume, self).get_parser(prog_name)
         parser.add_argument(
             '--project',
-            metavar='<project-id>',
+            metavar='<project>',
             help='Filter results by project (name or ID) (admin only)'
         )
         identity_common.add_project_domain_option_to_parser(parser)
         parser.add_argument(
             '--user',
-            metavar='<user-id>',
+            metavar='<user>',
             help='Filter results by user (name or ID) (admin only)'
         )
         identity_common.add_user_domain_option_to_parser(parser)
@@ -320,36 +320,36 @@ class SetVolume(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(
             '--name',
             metavar='<name>',
             help='New volume name',
         )
-        parser.add_argument(
-            '--description',
-            metavar='<description>',
-            help='New volume description',
-        )
         parser.add_argument(
             '--size',
             metavar='<size>',
             type=int,
             help='Extend volume size in GB',
         )
+        parser.add_argument(
+            '--description',
+            metavar='<description>',
+            help='New volume description',
+        )
         parser.add_argument(
             '--property',
             metavar='<key=value>',
             action=parseractions.KeyValueAction,
-            help='Property to add or modify for this volume '
+            help='Set a property on this volume '
                  '(repeat option to set multiple properties)',
         )
         parser.add_argument(
             '--image-property',
             metavar='<key=value>',
             action=parseractions.KeyValueAction,
-            help='To add or modify image properties for this volume '
+            help='Set an image property on this volume '
                  '(repeat option to set multiple image properties)',
         )
         return parser
@@ -434,14 +434,14 @@ class UnsetVolume(command.Command):
             '--property',
             metavar='<key>',
             action='append',
-            help='Property to remove from volume '
+            help='Remove a property from volume '
                  '(repeat option to remove multiple properties)',
         )
         parser.add_argument(
             '--image-property',
             metavar='<key>',
             action='append',
-            help='To remove image properties from volume '
+            help='Remove an image property from volume '
                  '(repeat option to remove multiple image properties)',
         )
         return parser