Merge "Docs cleanup: volume command help"

3 files changed, 106 insertions, 88 deletions

diff --git a/doc/source/command-objects/volume.rst b/doc/source/command-objects/volume.rst
index fd32c327..a51d1117 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>
+        [--type <volume-type>]
+        [--image <image>]
         [--snapshot <snapshot>]
+        [--source <volume>]
         [--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
+    Volume size in GB
+
+.. option:: --type <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 <snapshot> as source of new volume
+    Use :option:`\<snapshot\>` as source of volume (name or ID)
 
-.. option:: --description <description>
+.. option:: --source <source>
 
-    New volume description
+    Volume to clone (name or ID)
 
-.. option:: --type <volume-type>
+.. option:: --description <description>
 
-    Use <volume-type> as the new volume type
+    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 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