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

2 files changed, 56 insertions, 56 deletions

diff --git a/openstackclient/volume/v1/volume.py b/openstackclient/volume/v1/volume.py
index 90827d20..29c197ef 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 5d9d2d9e..5b7511e8 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"
+            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)",
         )
         parser.add_argument(
             "--snapshot",
             metavar="<snapshot>",
-            help="Use <snapshot> as source of new volume (name or ID)"
+            help="Use <snapshot> as source of volume (name or ID)",
         )
         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',
@@ -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,7 +320,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',
@@ -328,28 +328,28 @@ class SetVolume(command.Command):
             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