Improve help strings

Improve consistency of help strings:
* Add "." at end of help strings and descriptions.
* Improve descriptions.
* Fix capitalization.

Change-Id: I291acea95871734a30192c2e4564267326f9c0a7

1 files changed, 71 insertions, 65 deletions

diff --git a/keystoneclient/v2_0/shell.py b/keystoneclient/v2_0/shell.py
index d738ee9..087d3ed 100755
--- a/keystoneclient/v2_0/shell.py
+++ b/keystoneclient/v2_0/shell.py
@@ -47,7 +47,7 @@ def require_service_catalog(f):
 
 
 @utils.arg('--tenant', '--tenant-id', metavar='<tenant>',
-           help='Tenant;  lists all users if not specified')
+           help='Tenant;  lists all users if not specified.')
 @utils.arg('--tenant_id', help=argparse.SUPPRESS)
 def do_user_list(kc, args):
     """List users."""
@@ -60,7 +60,7 @@ def do_user_list(kc, args):
                      order_by='name')
 
 
-@utils.arg('user', metavar='<user>', help='Name or ID of user to display')
+@utils.arg('user', metavar='<user>', help='Name or ID of user to display.')
 def do_user_get(kc, args):
     """Display user details."""
     user = utils.find_resource(kc.users, args.user)
@@ -68,16 +68,16 @@ def do_user_get(kc, args):
 
 
 @utils.arg('--name', metavar='<user-name>', required=True,
-           help='New user name (must be unique)')
+           help='New user name (must be unique).')
 @utils.arg('--tenant', '--tenant-id', metavar='<tenant>',
-           help='New user default tenant')
+           help='New user default tenant.')
 @utils.arg('--tenant_id', help=argparse.SUPPRESS)
 @utils.arg('--pass', metavar='<pass>', dest='passwd', nargs='?',
-           const=ASK_FOR_PASSWORD, help='New user password')
+           const=ASK_FOR_PASSWORD, help='New user password.')
 @utils.arg('--email', metavar='<email>',
-           help='New user email address')
+           help='New user email address.')
 @utils.arg('--enabled', metavar='<true|false>', default=True,
-           help='Initial user enabled status (default true)')
+           help='Initial user enabled status. Default is true.')
 def do_user_create(kc, args):
     """Create new user"""
     if args.tenant:
@@ -96,12 +96,12 @@ def do_user_create(kc, args):
 
 
 @utils.arg('--name', metavar='<user-name>',
-           help='Desired new user name')
+           help='Desired new user name.')
 @utils.arg('--email', metavar='<email>',
-           help='Desired new email address')
+           help='Desired new email address.')
 @utils.arg('--enabled', metavar='<true|false>',
-           help='Enable or disable user')
-@utils.arg('user', metavar='<user>', help='Name or ID of user to update')
+           help='Enable or disable user.')
+@utils.arg('user', metavar='<user>', help='Name or ID of user to update.')
 def do_user_update(kc, args):
     """Update user's name, email, and enabled status."""
     kwargs = {}
@@ -125,9 +125,9 @@ def do_user_update(kc, args):
 
 
 @utils.arg('--pass', metavar='<password>', dest='passwd', required=False,
-           help='Desired new password')
+           help='Desired new password.')
 @utils.arg('user', metavar='<user>',
-           help='Name or ID of user to update password')
+           help='Name or ID of user to update password.')
 def do_user_password_update(kc, args):
     """Update user password."""
     user = utils.find_resource(kc.users, args.user)
@@ -142,9 +142,9 @@ def do_user_password_update(kc, args):
 @utils.arg('--current-password', metavar='<current-password>',
            dest='currentpasswd', required=False, help='Current password, '
                 'Defaults to the password as set by --os-password or '
-                'OS_PASSWORD')
+                'env[OS_PASSWORD].')
 @utils.arg('--new-password ', metavar='<new-password>', dest='newpasswd',
-           required=False, help='Desired new password')
+           required=False, help='Desired new password.')
 def do_password_update(kc, args):
     """Update own password."""
 
@@ -171,9 +171,9 @@ def do_password_update(kc, args):
               "to match your new password")
 
 
-@utils.arg('user', metavar='<user>', help='Name or ID of user to delete')
+@utils.arg('user', metavar='<user>', help='Name or ID of user to delete.')
 def do_user_delete(kc, args):
-    """Delete user"""
+    """Delete user."""
     user = utils.find_resource(kc.users, args.user)
     kc.users.delete(user)
 
@@ -185,7 +185,7 @@ def do_tenant_list(kc, args):
 
 
 @utils.arg('tenant', metavar='<tenant>',
-           help='Name or ID of tenant to display')
+           help='Name or ID of tenant to display.')
 def do_tenant_get(kc, args):
     """Display tenant details."""
     tenant = utils.find_resource(kc.tenants, args.tenant)
@@ -193,11 +193,11 @@ def do_tenant_get(kc, args):
 
 
 @utils.arg('--name', metavar='<tenant-name>', required=True,
-           help='New tenant name (must be unique)')
+           help='New tenant name (must be unique).')
 @utils.arg('--description', metavar='<tenant-description>', default=None,
-           help='Description of new tenant (default is none)')
+           help='Description of new tenant. Default is none.')
 @utils.arg('--enabled', metavar='<true|false>', default=True,
-           help='Initial tenant enabled status (default true)')
+           help='Initial tenant enabled status. Default is true.')
 def do_tenant_create(kc, args):
     """Create new tenant."""
     tenant = kc.tenants.create(args.name,
@@ -207,12 +207,13 @@ def do_tenant_create(kc, args):
 
 
 @utils.arg('--name', metavar='<tenant_name>',
-           help='Desired new name of tenant')
+           help='Desired new name of tenant.')
 @utils.arg('--description', metavar='<tenant-description>', default=None,
-           help='Desired new description of tenant')
+           help='Desired new description of tenant.')
 @utils.arg('--enabled', metavar='<true|false>',
-           help='Enable or disable tenant')
-@utils.arg('tenant', metavar='<tenant>', help='Name or ID of tenant to update')
+           help='Enable or disable tenant.')
+@utils.arg('tenant', metavar='<tenant>',
+           help='Name or ID of tenant to update.')
 def do_tenant_update(kc, args):
     """Update tenant name, description, enabled status."""
     tenant = utils.find_resource(kc.tenants, args.tenant)
@@ -230,7 +231,8 @@ def do_tenant_update(kc, args):
     tenant.update(**kwargs)
 
 
-@utils.arg('tenant', metavar='<tenant>', help='Name or ID of tenant to delete')
+@utils.arg('tenant', metavar='<tenant>',
+           help='Name or ID of tenant to delete.')
 def do_tenant_delete(kc, args):
     """Delete tenant."""
     tenant = utils.find_resource(kc.tenants, args.tenant)
@@ -238,12 +240,12 @@ def do_tenant_delete(kc, args):
 
 
 @utils.arg('--name', metavar='<name>', required=True,
-           help='Name of new service (must be unique)')
+           help='Name of new service (must be unique).')
 @utils.arg('--type', metavar='<type>', required=True,
            help='Service type (one of: identity, compute, network, '
-                'image, object-store, or other service identifier string)')
+                'image, object-store, or other service identifier string).')
 @utils.arg('--description', metavar='<service-description>',
-           help='Description of service')
+           help='Description of service.')
 def do_service_create(kc, args):
     """Add service to Service Catalog."""
     service = kc.services.create(args.name,
@@ -260,7 +262,7 @@ def do_service_list(kc, args):
 
 
 @utils.arg('service', metavar='<service>',
-           help='Name or ID of service to display')
+           help='Name or ID of service to display.')
 def do_service_get(kc, args):
     """Display service from Service Catalog."""
     service = utils.find_resource(kc.services, args.service)
@@ -268,7 +270,7 @@ def do_service_get(kc, args):
 
 
 @utils.arg('service', metavar='<service>',
-           help='Name or ID of service to delete')
+           help='Name or ID of service to delete.')
 def do_service_delete(kc, args):
     """Delete service from Service Catalog."""
     service = utils.find_resource(kc.services, args.service)
@@ -281,7 +283,7 @@ def do_role_list(kc, args):
     utils.print_list(roles, ['id', 'name'], order_by='name')
 
 
-@utils.arg('role', metavar='<role>', help='Name or ID of role to display')
+@utils.arg('role', metavar='<role>', help='Name or ID of role to display.')
 def do_role_get(kc, args):
     """Display role details."""
     role = utils.find_resource(kc.roles, args.role)
@@ -289,14 +291,14 @@ def do_role_get(kc, args):
 
 
 @utils.arg('--name', metavar='<role-name>', required=True,
-           help='Name of new role')
+           help='Name of new role.')
 def do_role_create(kc, args):
     """Create new role."""
     role = kc.roles.create(args.name)
     utils.print_dict(role._info)
 
 
-@utils.arg('role', metavar='<role>', help='Name or ID of role to delete')
+@utils.arg('role', metavar='<role>', help='Name or ID of role to delete.')
 def do_role_delete(kc, args):
     """Delete role."""
     role = utils.find_resource(kc.roles, args.role)
@@ -304,14 +306,14 @@ def do_role_delete(kc, args):
 
 
 @utils.arg('--user', '--user-id', '--user_id', metavar='<user>',
-           required=True, help='Name or ID of user')
+           required=True, help='Name or ID of user.')
 @utils.arg('--role', '--role-id', '--role_id', metavar='<role>',
-           required=True, help='Name or ID of role')
+           required=True, help='Name or ID of role.')
 @utils.arg('--tenant', '--tenant-id', metavar='<tenant>',
-           help='Name or ID of tenant')
+           help='Name or ID of tenant.')
 @utils.arg('--tenant_id', help=argparse.SUPPRESS)
 def do_user_role_add(kc, args):
-    """Add role to user"""
+    """Add role to user."""
     user = utils.find_resource(kc.users, args.user)
     role = utils.find_resource(kc.roles, args.role)
     if args.tenant:
@@ -324,14 +326,14 @@ def do_user_role_add(kc, args):
 
 
 @utils.arg('--user', '--user-id', '--user_id', metavar='<user>',
-           required=True, help='Name or ID of user')
+           required=True, help='Name or ID of user.')
 @utils.arg('--role', '--role-id', '--role_id', metavar='<role>',
-           required=True, help='Name or ID of role')
+           required=True, help='Name or ID of role.')
 @utils.arg('--tenant', '--tenant-id', metavar='<tenant>',
-           help='Name or ID of tenant')
+           help='Name or ID of tenant.')
 @utils.arg('--tenant_id', help=argparse.SUPPRESS)
 def do_user_role_remove(kc, args):
-    """Remove role from user"""
+    """Remove role from user."""
     user = utils.find_resource(kc.users, args.user)
     role = utils.find_resource(kc.roles, args.role)
     if args.tenant:
@@ -344,13 +346,13 @@ def do_user_role_remove(kc, args):
 
 
 @utils.arg('--user', '--user-id', metavar='<user>',
-           help='List roles granted to a user')
+           help='List roles granted to specified user.')
 @utils.arg('--user_id', help=argparse.SUPPRESS)
 @utils.arg('--tenant', '--tenant-id', metavar='<tenant>',
-           help='List roles granted on a tenant')
+           help='List only roles granted on specified tenant.')
 @utils.arg('--tenant_id', help=argparse.SUPPRESS)
 def do_user_role_list(kc, args):
-    """List roles granted to a user"""
+    """List roles granted to a user."""
     if args.tenant:
         tenant_id = utils.find_resource(kc.tenants, args.tenant).id
     elif args.tenant_id:
@@ -377,9 +379,13 @@ def do_user_role_list(kc, args):
                      order_by='name')
 
 
-@utils.arg('--user-id', metavar='<user-id>', help='User ID')
+@utils.arg('--user-id', metavar='<user-id>',
+           help='User ID for which to create credentials. If not specified, '
+           'the authenticated user will be used.')
 @utils.arg('--user_id', help=argparse.SUPPRESS)
-@utils.arg('--tenant-id', metavar='<tenant-id>', help='Tenant ID')
+@utils.arg('--tenant-id', metavar='<tenant-id>',
+           help='Tenant ID for which to to create credentials. If not '
+           'specified, the authenticated tenant ID will be used.')
 @utils.arg('--tenant_id', help=argparse.SUPPRESS)
 def do_ec2_credentials_create(kc, args):
     """Create EC2-compatible credentials for user per tenant."""
@@ -393,10 +399,10 @@ def do_ec2_credentials_create(kc, args):
     utils.print_dict(credentials._info)
 
 
-@utils.arg('--user-id', metavar='<user-id>', help='User ID')
+@utils.arg('--user-id', metavar='<user-id>', help='User ID.')
 @utils.arg('--user_id', help=argparse.SUPPRESS)
 @utils.arg('--access', metavar='<access-key>', required=True,
-           help='Access Key')
+           help='Access Key.')
 def do_ec2_credentials_get(kc, args):
     """Display EC2-compatible credentials."""
     if not args.user_id:
@@ -407,10 +413,10 @@ def do_ec2_credentials_get(kc, args):
         utils.print_dict(cred._info)
 
 
-@utils.arg('--user-id', metavar='<user-id>', help='User ID')
+@utils.arg('--user-id', metavar='<user-id>', help='User ID.')
 @utils.arg('--user_id', help=argparse.SUPPRESS)
 def do_ec2_credentials_list(kc, args):
-    """List EC2-compatible credentials for a user"""
+    """List EC2-compatible credentials for a user."""
     if not args.user_id:
         # use the authenticated user id as a default
         args.user_id = kc.auth_user_id
@@ -425,10 +431,10 @@ def do_ec2_credentials_list(kc, args):
     utils.print_list(credentials, ['tenant', 'access', 'secret'])
 
 
-@utils.arg('--user-id', metavar='<user-id>', help='User ID')
+@utils.arg('--user-id', metavar='<user-id>', help='User ID.')
 @utils.arg('--user_id', help=argparse.SUPPRESS)
 @utils.arg('--access', metavar='<access-key>', required=True,
-           help='Access Key')
+           help='Access Key.')
 def do_ec2_credentials_delete(kc, args):
     """Delete EC2-compatible credentials."""
     if not args.user_id:
@@ -442,7 +448,7 @@ def do_ec2_credentials_delete(kc, args):
 
 
 @utils.arg('--service', metavar='<service-type>', default=None,
-           help='Service type to return')
+           help='Service type to return.')
 @require_service_catalog
 def do_catalog(kc, args):
     """List service catalog, possibly filtered by service."""
@@ -455,15 +461,15 @@ def do_catalog(kc, args):
 
 
 @utils.arg('--service', metavar='<service-type>', required=True,
-           help='Service type to select')
+           help='Service type to select.')
 @utils.arg('--endpoint-type', metavar='<endpoint-type>', default='publicURL',
-           help='Endpoint type to select')
+           help='Endpoint type to select.')
 @utils.arg('--endpoint_type', default='publicURL',
            help=argparse.SUPPRESS)
 @utils.arg('--attr', metavar='<service-attribute>',
-           help='Service attribute to match for selection')
+           help='Service attribute to match for selection.')
 @utils.arg('--value', metavar='<value>',
-           help='Value of attribute to match')
+           help='Value of attribute to match.')
 @require_service_catalog
 def do_endpoint_get(kc, args):
     """Find endpoint filtered by a specific attribute or service type."""
@@ -491,16 +497,16 @@ def do_endpoint_list(kc, args):
 
 
 @utils.arg('--region', metavar='<endpoint-region>',
-           help='Endpoint region', default='regionOne')
+           help='Endpoint region.', default='regionOne')
 @utils.arg('--service', '--service-id', '--service_id',
            metavar='<service>', required=True,
-           help='Name or ID of service associated with Endpoint')
+           help='Name or ID of service associated with endpoint.')
 @utils.arg('--publicurl', metavar='<public-url>', required=True,
-           help='Public URL endpoint')
+           help='Public URL endpoint.')
 @utils.arg('--adminurl', metavar='<admin-url>',
-           help='Admin URL endpoint')
+           help='Admin URL endpoint.')
 @utils.arg('--internalurl', metavar='<internal-url>',
-           help='Internal URL endpoint')
+           help='Internal URL endpoint.')
 def do_endpoint_create(kc, args):
     """Create a new endpoint associated with a service."""
     service_id = utils.find_resource(kc.services, args.service).id
@@ -512,7 +518,7 @@ def do_endpoint_create(kc, args):
     utils.print_dict(endpoint._info)
 
 
-@utils.arg('id', metavar='<endpoint-id>', help='ID of endpoint to delete')
+@utils.arg('id', metavar='<endpoint-id>', help='ID of endpoint to delete.')
 def do_endpoint_delete(kc, args):
     """Delete a service endpoint."""
     try:
@@ -523,7 +529,7 @@ def do_endpoint_delete(kc, args):
 
 
 @utils.arg('--wrap', metavar='<integer>', default=0,
-           help='wrap PKI tokens to a specified length, or 0 to disable')
+           help='Wrap PKI tokens to a specified length, or 0 to disable.')
 @require_service_catalog
 def do_token_get(kc, args):
     """Display the current user token."""