From 1686dc54f09b6e77b1de3abc708c297710987a04 Mon Sep 17 00:00:00 2001
From: Dean Troyer <dtroyer@gmail.com>
Date: Mon, 3 Apr 2017 16:15:14 -0500
Subject: Help/docs cleanups: marker, limit, ip-address metavars

Cleanup help strings and docs for clarity and to keep things consistent:
* --limit metavar should be <num-resource> to indicate what is being counted
* --marker metavar should be <resource> or <resource-id> to indicate the
  type of value being specified
* <*-ip-address> metavars should be just <ip-address> as there is no difference
  in format between fixed and floating IPs
* Move all occurances of '(name or ID)' to end of help text

Change-Id: I2c31746ed6ded3845244e03e57d809f8bc0e6b9d
---
 doc/source/command-objects/container.rst       |  4 ++--
 doc/source/command-objects/flavor.rst          |  8 ++++----
 doc/source/command-objects/floating-ip.rst     | 12 +++++------
 doc/source/command-objects/image.rst           | 16 +++++++++------
 doc/source/command-objects/object.rst          |  4 ++--
 doc/source/command-objects/port.rst            | 10 ++++-----
 doc/source/command-objects/server.rst          | 28 +++++++++++++-------------
 doc/source/command-objects/snapshot.rst        |  8 ++++----
 doc/source/command-objects/subnet-pool.rst     |  2 +-
 doc/source/command-objects/subnet.rst          |  4 ++--
 doc/source/command-objects/volume-backup.rst   |  8 ++++----
 doc/source/command-objects/volume-snapshot.rst |  8 ++++----
 doc/source/command-objects/volume.rst          |  8 ++++----
 13 files changed, 62 insertions(+), 58 deletions(-)

(limited to 'doc/source/command-objects')

diff --git a/doc/source/command-objects/container.rst b/doc/source/command-objects/container.rst
index c4310472..e68955ad 100644
--- a/doc/source/command-objects/container.rst
+++ b/doc/source/command-objects/container.rst
@@ -51,7 +51,7 @@ List containers
         [--prefix <prefix>]
         [--marker <marker>]
         [--end-marker <end-marker>]
-        [--limit <limit>]
+        [--limit <num-containers>]
         [--long]
         [--all]
 
@@ -67,7 +67,7 @@ List containers
 
     End anchor for paging
 
-.. option:: --limit <limit>
+.. option:: --limit <num-containers>
 
     Limit the number of containers returned
 
diff --git a/doc/source/command-objects/flavor.rst b/doc/source/command-objects/flavor.rst
index a9f8262e..6feb4498 100644
--- a/doc/source/command-objects/flavor.rst
+++ b/doc/source/command-objects/flavor.rst
@@ -108,8 +108,8 @@ List flavors
     openstack flavor list
         [--public | --private | --all]
         [--long]
-        [--marker <marker>]
-        [--limit <limit>]
+        [--marker <flavor-id>]
+        [--limit <num-flavors>]
 
 .. option:: --public
 
@@ -127,11 +127,11 @@ List flavors
 
     List additional fields in output
 
-.. option:: --marker <marker>
+.. option:: --marker <flavor-id>
 
     The last flavor ID of the previous page
 
-.. option:: --limit <limit>
+.. option:: --limit <num-flavors>
 
     Maximum number of flavors to display
 
diff --git a/doc/source/command-objects/floating-ip.rst b/doc/source/command-objects/floating-ip.rst
index 5a38bc1b..cbb473b8 100644
--- a/doc/source/command-objects/floating-ip.rst
+++ b/doc/source/command-objects/floating-ip.rst
@@ -15,8 +15,8 @@ Create floating IP
     openstack floating ip create
         [--subnet <subnet>]
         [--port <port>]
-        [--floating-ip-address <floating-ip-address>]
-        [--fixed-ip-address <fixed-ip-address>]
+        [--floating-ip-address <ip-address>]
+        [--fixed-ip-address <ip-address>]
         [--description <description>]
         [--project <project> [--project-domain <project-domain>]]
         <network>
@@ -31,12 +31,12 @@ Create floating IP
     Port to be associated with the floating IP (name or ID)
     *Network version 2 only*
 
-.. option:: --floating-ip-address <floating-ip-address>
+.. option:: --floating-ip-address <ip-address>
 
     Floating IP address
     *Network version 2 only*
 
-.. option:: --fixed-ip-address <fixed-ip-address>
+.. option:: --fixed-ip-address <ip-address>
 
     Fixed IP address mapped to the floating IP
     *Network version 2 only*
@@ -88,7 +88,7 @@ List floating IP(s)
     openstack floating ip list
         [--network <network>]
         [--port <port>]
-        [--fixed-ip-address <fixed-ip-address>]
+        [--fixed-ip-address <ip-address>]
         [--long]
         [--status <status>]
         [--project <project> [--project-domain <project-domain>]]
@@ -106,7 +106,7 @@ List floating IP(s)
 
     *Network version 2 only*
 
-.. option:: --fixed-ip-address <fixed-ip-address>
+.. option:: --fixed-ip-address <ip-address>
 
     List floating IP(s) according to given fixed IP address
 
diff --git a/doc/source/command-objects/image.rst b/doc/source/command-objects/image.rst
index c39d9a28..ec51fa93 100644
--- a/doc/source/command-objects/image.rst
+++ b/doc/source/command-objects/image.rst
@@ -199,8 +199,8 @@ List available images
         [--property <key=value>]
         [--long]
         [--sort <key>[:<direction>]]
-        [--limit <limit>]
-        [--marker <marker>]
+        [--limit <num-images>]
+        [--marker <image>]
 
 .. option:: --public
 
@@ -229,14 +229,18 @@ List available images
     Sort output by selected keys and directions(asc or desc) (default: name:asc),
     multiple keys and directions can be specified separated by comma
 
-.. option:: --limit <limit>
+.. option:: --limit <num-images>
 
     Maximum number of images to display.
 
-.. option:: --marker <marker>
+    *Image version 2 only*
 
-    The last image (name or ID) of the previous page. Display list of images
-    after marker. Display all images if not specified.
+.. option:: --marker <image>
+
+    The last image of the previous page. Display list of images
+    after marker. Display all images if not specified. (name or ID)
+
+    *Image version 2 only*
 
 image remove project
 --------------------
diff --git a/doc/source/command-objects/object.rst b/doc/source/command-objects/object.rst
index 0a32a827..6323c4ed 100644
--- a/doc/source/command-objects/object.rst
+++ b/doc/source/command-objects/object.rst
@@ -62,7 +62,7 @@ List objects
         [--delimiter <delimiter>]
         [--marker <marker>]
         [--end-marker <end-marker>]
-        [--limit <limit>]
+        [--limit <num-objects>]
         [--long]
         [--all]
         <container>
@@ -83,7 +83,7 @@ List objects
 
     End anchor for paging
 
-.. option:: --limit <limit>
+.. option:: --limit <num-objects>
 
     Limit number of objects returned
 
diff --git a/doc/source/command-objects/port.rst b/doc/source/command-objects/port.rst
index 98642b9a..ddfbb445 100644
--- a/doc/source/command-objects/port.rst
+++ b/doc/source/command-objects/port.rst
@@ -44,7 +44,7 @@ Create new port
 
 .. option:: --fixed-ip subnet=<subnet>,ip-address=<ip-address>
 
-    Desired IP and/or subnet (name or ID) for this port:
+    Desired IP and/or subnet for this port (name or ID):
     subnet=<subnet>,ip-address=<ip-address>
     (repeat option to set multiple fixed IP addresses)
 
@@ -182,7 +182,7 @@ List ports
 
 .. option:: --fixed-ip subnet=<subnet>,ip-address=<ip-address>
 
-    Desired IP and/or subnet (name or ID) for filtering ports:
+    Desired IP and/or subnet for filtering ports (name or ID):
     subnet=<subnet>,ip-address=<ip-address>
     (repeat option to set multiple fixed IP addresses)
 
@@ -234,7 +234,7 @@ Set port properties
 
 .. option:: --fixed-ip subnet=<subnet>,ip-address=<ip-address>
 
-    Desired IP and/or subnet (name or ID) for this port:
+    Desired IP and/or subnet for this port (name or ID):
     subnet=<subnet>,ip-address=<ip-address>
     (repeat option to set multiple fixed IP addresses)
 
@@ -363,8 +363,8 @@ Unset port properties
 
 .. option:: --fixed-ip subnet=<subnet>,ip-address=<ip-address>
 
-    Desired IP and/or subnet (name or ID) which should be removed
-    from this port: subnet=<subnet>,ip-address=<ip-address>
+    Desired IP and/or subnet which should be removed
+    from this port (name or ID): subnet=<subnet>,ip-address=<ip-address>
     (repeat option to unset multiple fixed IP addresses)
 
 .. option:: --binding-profile <binding-profile-key>
diff --git a/doc/source/command-objects/server.rst b/doc/source/command-objects/server.rst
index 047bf181..ce4e168d 100644
--- a/doc/source/command-objects/server.rst
+++ b/doc/source/command-objects/server.rst
@@ -18,11 +18,11 @@ Add fixed IP address to server
 
 .. describe:: <server>
 
-    Server (name or ID) to receive the fixed IP address
+    Server to receive the fixed IP address (name or ID)
 
 .. describe:: <network>
 
-    Network (name or ID) to allocate the fixed IP address from
+    Network to allocate the fixed IP address from (name or ID)
 
 server add floating ip
 ----------------------
@@ -33,21 +33,21 @@ Add floating IP address to server
 .. code:: bash
 
     openstack server add floating ip
-        [--fixed-ip-address <fixed-ip-address>]
+        [--fixed-ip-address <ip-address>]
         <server>
         <ip-address>
 
-.. option:: --fixed-ip-address <fixed-ip-address>
+.. option:: --fixed-ip-address <ip-address>
 
     Fixed IP address to associate with this floating IP address
 
 .. describe:: <server>
 
-    Server (name or ID) to receive the floating IP address
+    Server to receive the floating IP address (name or ID)
 
 .. describe:: <ip-address>
 
-    Floating IP address (IP address only) to assign to server
+    Floating IP address to assign to server (IP only)
 
 server add security group
 -------------------------
@@ -264,7 +264,7 @@ List servers
         [--project <project> [--project-domain <project-domain>]]
         [--long]
         [--marker <server>]
-        [--limit <limit>]
+        [--limit <num-servers>]
         [--deleted]
         [--changes-since <changes-since>]
 
@@ -332,10 +332,10 @@ List servers
 
 .. option:: --marker <server>
 
-    The last server (name or ID) of the previous page. Display list of servers
-    after marker. Display all servers if not specified.
+    The last server of the previous page. Display list of servers
+    after marker. Display all servers if not specified. (name or ID)
 
-.. option:: --limit <limit>
+.. option:: --limit <num-servers>
 
     Maximum number of servers to display. If limit equals -1, all servers will
     be displayed. If limit is greater than 'osapi_max_limit' option of Nova
@@ -497,11 +497,11 @@ Remove fixed IP address from server
 
 .. describe:: <server>
 
-    Server (name or ID) to remove the fixed IP address from
+    Server to remove the fixed IP address from (name or ID)
 
 .. describe:: <ip-address>
 
-    Fixed IP address (IP address only) to remove from the server
+    Fixed IP address to remove from the server (IP only)
 
 server remove floating ip
 -------------------------
@@ -517,11 +517,11 @@ Remove floating IP address from server
 
 .. describe:: <server>
 
-    Server (name or ID) to remove the floating IP address from
+    Server to remove the floating IP address from (name or ID)
 
 .. describe:: <ip-address>
 
-    Floating IP address (IP address only) to remove from server
+    Floating IP address to remove from server (IP only)
 
 server remove security group
 ----------------------------
diff --git a/doc/source/command-objects/snapshot.rst b/doc/source/command-objects/snapshot.rst
index c5c431d0..fc516067 100644
--- a/doc/source/command-objects/snapshot.rst
+++ b/doc/source/command-objects/snapshot.rst
@@ -72,8 +72,8 @@ List snapshots
     openstack snapshot list
         [--all-projects]
         [--long]
-        [--limit <limit>]
-        [--marker <marker>]
+        [--limit <num-snapshots>]
+        [--marker <snapshot>]
 
 .. option:: --all-projects
 
@@ -83,13 +83,13 @@ List snapshots
 
     List additional fields in output
 
-.. option:: --limit <limit>
+.. option:: --limit <num-snapshots>
 
     Maximum number of snapshots to display
 
     *Volume version 2 only*
 
-.. option:: --marker <marker>
+.. option:: --marker <snapshot>
 
     The last snapshot ID of the previous page
 
diff --git a/doc/source/command-objects/subnet-pool.rst b/doc/source/command-objects/subnet-pool.rst
index 8b59bf8a..d47673de 100644
--- a/doc/source/command-objects/subnet-pool.rst
+++ b/doc/source/command-objects/subnet-pool.rst
@@ -150,7 +150,7 @@ List subnet pools
 
 .. option:: --address-scope <address-scope>
 
-    List only subnet pools of given address scope (name or ID) in output
+    List only subnet pools of given address scope in output (name or ID)
 
 subnet pool set
 ---------------
diff --git a/doc/source/command-objects/subnet.rst b/doc/source/command-objects/subnet.rst
index 5eb55c23..4e609361 100644
--- a/doc/source/command-objects/subnet.rst
+++ b/doc/source/command-objects/subnet.rst
@@ -194,7 +194,7 @@ List subnets
 
 .. option:: --project <project>
 
-    List only subnets which belong to a given project (name or ID) in output
+    List only subnets which belong to a given project in output (name or ID)
 
 .. option:: --project-domain <project-domain>
 
@@ -203,7 +203,7 @@ List subnets
 
 .. option:: --network <network>
 
-    List only subnets which belong to a given network (name or ID) in output
+    List only subnets which belong to a given network in output (name or ID)
 
 .. option:: --gateway <gateway>
 
diff --git a/doc/source/command-objects/volume-backup.rst b/doc/source/command-objects/volume-backup.rst
index f2f814c5..585f47d4 100644
--- a/doc/source/command-objects/volume-backup.rst
+++ b/doc/source/command-objects/volume-backup.rst
@@ -92,8 +92,8 @@ List volume backups
         [--name <name>]
         [--status <status>]
         [--volume <volume>]
-        [--marker <marker>]
-        [--limit <limit>]
+        [--marker <volume-backup>]
+        [--limit <num-backups>]
         [--all-projects]
 
 .. _volume_backup_list-backup:
@@ -114,13 +114,13 @@ List volume backups
 
     Filters results by the volume which they backup (name or ID)"
 
-.. option:: --marker <marker>
+.. option:: --marker <volume-backup>
 
     The last backup of the previous page (name or ID)
 
     *Volume version 2 only*
 
-.. option:: --limit <limit>
+.. option:: --limit <num-backups>
 
     Maximum number of backups to display
 
diff --git a/doc/source/command-objects/volume-snapshot.rst b/doc/source/command-objects/volume-snapshot.rst
index 449e45b9..67db62f2 100644
--- a/doc/source/command-objects/volume-snapshot.rst
+++ b/doc/source/command-objects/volume-snapshot.rst
@@ -84,8 +84,8 @@ List volume snapshots
         [--all-projects]
         [--project <project> [--project-domain <project-domain>]]
         [--long]
-        [--limit <limit>]
-        [--marker <marker>]
+        [--limit <num-snapshots>]
+        [--marker <snapshot>]
         [--name <name>]
         [--status <status>]
         [--volume <volume>]
@@ -125,13 +125,13 @@ List volume snapshots
 
     Filters results by a volume (name or ID).
 
-.. option:: --limit <limit>
+.. option:: --limit <num-snapshots>
 
     Maximum number of snapshots to display
 
     *Volume version 2 only*
 
-.. option:: --marker <marker>
+.. option:: --marker <snapshot>
 
     The last snapshot ID of the previous page
 
diff --git a/doc/source/command-objects/volume.rst b/doc/source/command-objects/volume.rst
index 85a920eb..a06a5d40 100644
--- a/doc/source/command-objects/volume.rst
+++ b/doc/source/command-objects/volume.rst
@@ -158,8 +158,8 @@ List volumes
         [--status <status>]
         [--all-projects]
         [--long]
-        [--limit <limit>]
-        [--marker <marker>]
+        [--limit <num-volumes>]
+        [--marker <volume>]
 
 .. option:: --project <project>
 
@@ -205,11 +205,11 @@ List volumes
 
     List additional fields in output
 
-.. option:: --limit <limit>
+.. option:: --limit <num-volumes>
 
     Maximum number of volumes to display
 
-.. option:: --marker <marker>
+.. option:: --marker <volume>
 
     The last volume ID of the previous page
 
-- 
cgit v1.2.1