Command object docs: project, role, user

project
role
user
user role

Change-Id: I445e09a3ffb69114912ae562a9285963a636bfd1

6 files changed, 150 insertions, 139 deletions

diff --git a/openstackclient/identity/v2_0/project.py b/openstackclient/identity/v2_0/project.py
index 2d66b400..df759ce6 100644
--- a/openstackclient/identity/v2_0/project.py
+++ b/openstackclient/identity/v2_0/project.py
@@ -42,8 +42,8 @@ class CreateProject(show.ShowOne):
         )
         parser.add_argument(
             '--description',
-            metavar='<project-description>',
-            help=_('New project description'),
+            metavar='<description>',
+            help=_('Project description'),
         )
         enable_group = parser.add_mutually_exclusive_group()
         enable_group.add_argument(
@@ -60,7 +60,7 @@ class CreateProject(show.ShowOne):
             '--property',
             metavar='<key=value>',
             action=parseractions.KeyValueAction,
-            help=_('Property to add for this project '
+            help=_('Add a property to <name> '
                    '(repeat option to set multiple properties)'),
         )
         parser.add_argument(
@@ -104,7 +104,7 @@ class CreateProject(show.ShowOne):
 
 
 class DeleteProject(command.Command):
-    """Delete project"""
+    """Delete an existing project"""
 
     log = logging.getLogger(__name__ + '.DeleteProject')
 
@@ -169,17 +169,17 @@ class SetProject(command.Command):
         parser.add_argument(
             'project',
             metavar='<project>',
-            help=_('Project to change (name or ID)'),
+            help=_('Project to modify (name or ID)'),
         )
         parser.add_argument(
             '--name',
-            metavar='<new-project-name>',
-            help=_('New project name'),
+            metavar='<name>',
+            help=_('Set project name'),
         )
         parser.add_argument(
             '--description',
-            metavar='<project-description>',
-            help=_('New project description'),
+            metavar='<description>',
+            help=_('Set project description'),
         )
         enable_group = parser.add_mutually_exclusive_group()
         enable_group.add_argument(
@@ -196,7 +196,7 @@ class SetProject(command.Command):
             '--property',
             metavar='<key=value>',
             action=parseractions.KeyValueAction,
-            help=_('Property to add for this project '
+            help=_('Set a project property '
                    '(repeat option to set multiple properties)'),
         )
         return parser
@@ -249,7 +249,7 @@ class ShowProject(show.ShowOne):
         parser.add_argument(
             'project',
             metavar='<project>',
-            help=_('Project to display (name or ID)'))
+            help=_('Project to show (name or ID)'))
         return parser
 
     def take_action(self, parsed_args):
diff --git a/openstackclient/identity/v2_0/role.py b/openstackclient/identity/v2_0/role.py
index df69e857..cec95095 100644
--- a/openstackclient/identity/v2_0/role.py
+++ b/openstackclient/identity/v2_0/role.py
@@ -38,17 +38,20 @@ class AddRole(show.ShowOne):
         parser.add_argument(
             'role',
             metavar='<role>',
-            help=_('Role name or ID to add to user'))
+            help=_('Role to add to <project>:<user> (name or ID)'),
+        )
         parser.add_argument(
             '--project',
             metavar='<project>',
             required=True,
-            help=_('Include project (name or ID)'))
+            help=_('Include <project> (name or ID)'),
+        )
         parser.add_argument(
             '--user',
             metavar='<user>',
             required=True,
-            help=_('Name or ID of user to include'))
+            help=_('Include <user> (name or ID)'),
+        )
         return parser
 
     def take_action(self, parsed_args):
@@ -80,8 +83,9 @@ class CreateRole(show.ShowOne):
         parser = super(CreateRole, self).get_parser(prog_name)
         parser.add_argument(
             'role_name',
-            metavar='<role-name>',
-            help=_('New role name'))
+            metavar='<name>',
+            help=_('New role name'),
+        )
         parser.add_argument(
             '--or-show',
             action='store_true',
@@ -110,7 +114,7 @@ class CreateRole(show.ShowOne):
 
 
 class DeleteRole(command.Command):
-    """Delete existing role"""
+    """Delete an existing role"""
 
     log = logging.getLogger(__name__ + '.DeleteRole')
 
@@ -119,7 +123,8 @@ class DeleteRole(command.Command):
         parser.add_argument(
             'role',
             metavar='<role>',
-            help=_('Name or ID of role to delete'))
+            help=_('Role to delete (name or ID)'),
+        )
         return parser
 
     def take_action(self, parsed_args):
@@ -162,11 +167,13 @@ class ListUserRole(lister.Lister):
             'user',
             metavar='<user>',
             nargs='?',
-            help=_('Name or ID of user to include'))
+            help=_('User to list (name or ID)'),
+        )
         parser.add_argument(
             '--project',
             metavar='<project>',
-            help=_('Include project (name or ID)'))
+            help=_('Filter users by <project> (name or ID)'),
+        )
         return parser
 
     def take_action(self, parsed_args):
@@ -227,17 +234,20 @@ class RemoveRole(command.Command):
         parser.add_argument(
             'role',
             metavar='<role>',
-            help=_('Role name or ID to remove from user'))
+            help=_('Role to remove from <project>:<user> (name or ID)'),
+        )
         parser.add_argument(
             '--project',
             metavar='<project>',
             required=True,
-            help=_('Project to include (name or ID)'))
+            help=_('Include <project> (name or ID)'),
+        )
         parser.add_argument(
             '--user',
             metavar='<user>',
             required=True,
-            help=_('Name or ID of user'))
+            help=_('Include <user> (name or ID)'),
+        )
         return parser
 
     def take_action(self, parsed_args):
@@ -265,7 +275,8 @@ class ShowRole(show.ShowOne):
         parser.add_argument(
             'role',
             metavar='<role>',
-            help=_('Name or ID of role to display'))
+            help=_('Role to show (name or ID)'),
+        )
         return parser
 
     def take_action(self, parsed_args):
diff --git a/openstackclient/identity/v2_0/user.py b/openstackclient/identity/v2_0/user.py
index 2ebcba18..955e19e7 100644
--- a/openstackclient/identity/v2_0/user.py
+++ b/openstackclient/identity/v2_0/user.py
@@ -36,13 +36,18 @@ class CreateUser(show.ShowOne):
         parser = super(CreateUser, self).get_parser(prog_name)
         parser.add_argument(
             'name',
-            metavar='<user-name>',
+            metavar='<name>',
             help=_('New user name'),
         )
         parser.add_argument(
+            '--project',
+            metavar='<project>',
+            help=_('Default project (name or ID)'),
+        )
+        parser.add_argument(
             '--password',
-            metavar='<user-password>',
-            help=_('New user password'),
+            metavar='<password>',
+            help=_('Set user password'),
         )
         parser.add_argument(
             '--password-prompt',
@@ -52,13 +57,8 @@ class CreateUser(show.ShowOne):
         )
         parser.add_argument(
             '--email',
-            metavar='<user-email>',
-            help=_('New user email address'),
-        )
-        parser.add_argument(
-            '--project',
-            metavar='<project>',
-            help=_('Set default project (name or ID)'),
+            metavar='<email-address>',
+            help=_('Set user email address'),
         )
         enable_group = parser.add_mutually_exclusive_group()
         enable_group.add_argument(
@@ -258,13 +258,18 @@ class SetUser(command.Command):
         )
         parser.add_argument(
             '--name',
-            metavar='<new-user-name>',
-            help=_('New user name'),
+            metavar='<name>',
+            help=_('Set user name'),
+        )
+        parser.add_argument(
+            '--project',
+            metavar='<project>',
+            help=_('Set default project (name or ID)'),
         )
         parser.add_argument(
             '--password',
             metavar='<user-password>',
-            help=_('New user password'),
+            help=_('Set user password'),
         )
         parser.add_argument(
             '--password-prompt',
@@ -274,13 +279,8 @@ class SetUser(command.Command):
         )
         parser.add_argument(
             '--email',
-            metavar='<user-email>',
-            help=_('New user email address'),
-        )
-        parser.add_argument(
-            '--project',
-            metavar='<project>',
-            help=_('New default project (name or ID)'),
+            metavar='<email-address>',
+            help=_('Set user email address'),
         )
         enable_group = parser.add_mutually_exclusive_group()
         enable_group.add_argument(
diff --git a/openstackclient/identity/v3/project.py b/openstackclient/identity/v3/project.py
index 4fcf8127..3b0e92fd 100644
--- a/openstackclient/identity/v3/project.py
+++ b/openstackclient/identity/v3/project.py
@@ -43,13 +43,13 @@ class CreateProject(show.ShowOne):
         )
         parser.add_argument(
             '--domain',
-            metavar='<project-domain>',
+            metavar='<domain>',
             help='Domain owning the project (name or ID)',
         )
         parser.add_argument(
             '--description',
-            metavar='<project-description>',
-            help='New project description',
+            metavar='<description>',
+            help='Project description',
         )
         enable_group = parser.add_mutually_exclusive_group()
         enable_group.add_argument(
@@ -66,7 +66,7 @@ class CreateProject(show.ShowOne):
             '--property',
             metavar='<key=value>',
             action=parseractions.KeyValueAction,
-            help='Property to add for this project '
+            help='Add a property to <name> '
                  '(repeat option to set multiple properties)',
         )
         parser.add_argument(
@@ -115,7 +115,7 @@ class CreateProject(show.ShowOne):
 
 
 class DeleteProject(command.Command):
-    """Delete project"""
+    """Delete an existing project"""
 
     log = logging.getLogger(__name__ + '.DeleteProject')
 
@@ -149,16 +149,16 @@ class ListProject(lister.Lister):
     def get_parser(self, prog_name):
         parser = super(ListProject, self).get_parser(prog_name)
         parser.add_argument(
+            '--domain',
+            metavar='<domain>',
+            help='Filter projects by <domain> (name or ID)',
+        )
+        parser.add_argument(
             '--long',
             action='store_true',
             default=False,
             help='List additional fields in output',
         )
-        parser.add_argument(
-            '--domain',
-            metavar='<project-domain>',
-            help='Filter by a specific domain (name or ID)',
-        )
         return parser
 
     def take_action(self, parsed_args):
@@ -190,22 +190,22 @@ class SetProject(command.Command):
         parser.add_argument(
             'project',
             metavar='<project>',
-            help='Project to change (name or ID)',
+            help='Project to modify (name or ID)',
         )
         parser.add_argument(
             '--name',
-            metavar='<new-project-name>',
-            help='New project name',
+            metavar='<name>',
+            help='Set project name',
         )
         parser.add_argument(
             '--domain',
-            metavar='<project-domain>',
-            help='New domain owning the project (name or ID)',
+            metavar='<domain>',
+            help='Set domain owning <project> (name or ID)',
         )
         parser.add_argument(
             '--description',
-            metavar='<project-description>',
-            help='New project description',
+            metavar='<description>',
+            help='Set project description',
         )
         enable_group = parser.add_mutually_exclusive_group()
         enable_group.add_argument(
@@ -222,7 +222,7 @@ class SetProject(command.Command):
             '--property',
             metavar='<key=value>',
             action=parseractions.KeyValueAction,
-            help='Property to add for this project '
+            help='Set a property on <project> '
                  '(repeat option to set multiple properties)',
         )
         return parser
@@ -278,7 +278,7 @@ class ShowProject(show.ShowOne):
         parser.add_argument(
             '--domain',
             metavar='<domain>',
-            help='Domain where project resides (name or ID)',
+            help='Domain owning <project> (name or ID)',
         )
         return parser
 
diff --git a/openstackclient/identity/v3/role.py b/openstackclient/identity/v3/role.py
index 7801ca65..017ffd76 100644
--- a/openstackclient/identity/v3/role.py
+++ b/openstackclient/identity/v3/role.py
@@ -38,29 +38,29 @@ class AddRole(command.Command):
         parser.add_argument(
             'role',
             metavar='<role>',
-            help='Name or ID of role to add',
-        )
-        user_or_group = parser.add_mutually_exclusive_group()
-        user_or_group.add_argument(
-            '--user',
-            metavar='<user>',
-            help='Name or ID of user to add a role',
-        )
-        user_or_group.add_argument(
-            '--group',
-            metavar='<group>',
-            help='Name or ID of group to add a role',
+            help='Role to add to <user> (name or ID)',
         )
         domain_or_project = parser.add_mutually_exclusive_group()
         domain_or_project.add_argument(
             '--domain',
             metavar='<domain>',
-            help='Name or ID of domain associated with user or group',
+            help='Include <domain> (name or ID)',
         )
         domain_or_project.add_argument(
             '--project',
             metavar='<project>',
-            help='Name or ID of project associated with user or group',
+            help='Include `<project>` (name or ID)',
+        )
+        user_or_group = parser.add_mutually_exclusive_group()
+        user_or_group.add_argument(
+            '--user',
+            metavar='<user>',
+            help='Include <user> (name or ID)',
+        )
+        user_or_group.add_argument(
+            '--group',
+            metavar='<group>',
+            help='Include <group> (name or ID)',
         )
         return parser
 
@@ -177,7 +177,7 @@ class CreateRole(show.ShowOne):
 
 
 class DeleteRole(command.Command):
-    """Delete existing role"""
+    """Delete an existing role"""
 
     log = logging.getLogger(__name__ + '.DeleteRole')
 
@@ -186,7 +186,7 @@ class DeleteRole(command.Command):
         parser.add_argument(
             'role',
             metavar='<role>',
-            help='Name or ID of role to delete',
+            help='Role to delete (name or ID)',
         )
         return parser
 
@@ -214,23 +214,23 @@ class ListRole(lister.Lister):
         domain_or_project.add_argument(
             '--domain',
             metavar='<domain>',
-            help='Filter role list by <domain>',
+            help='Filter roles by <domain> (name or ID)',
         )
         domain_or_project.add_argument(
             '--project',
             metavar='<project>',
-            help='Filter role list by <project>',
+            help='Filter roles by <project> (name or ID)',
         )
         user_or_group = parser.add_mutually_exclusive_group()
         user_or_group.add_argument(
             '--user',
             metavar='<user>',
-            help='Name or ID of user to list roles assigned to',
+            help='Filter roles by <user> (name or ID)',
         )
         user_or_group.add_argument(
             '--group',
             metavar='<group>',
-            help='Name or ID of group to list roles assigned to',
+            help='Filter roles by <group> (name or ID)',
         )
         return parser
 
@@ -320,7 +320,7 @@ class ListRole(lister.Lister):
 
 
 class RemoveRole(command.Command):
-    """Remove role command"""
+    """Remove role from domain/project : user/group"""
 
     log = logging.getLogger(__name__ + '.RemoveRole')
 
@@ -329,29 +329,29 @@ class RemoveRole(command.Command):
         parser.add_argument(
             'role',
             metavar='<role>',
-            help='Name or ID of role to remove',
-        )
-        user_or_group = parser.add_mutually_exclusive_group()
-        user_or_group.add_argument(
-            '--user',
-            metavar='<user>',
-            help='Name or ID of user to remove a role',
-        )
-        user_or_group.add_argument(
-            '--group',
-            metavar='<group>',
-            help='Name or ID of group to remove a role',
+            help='Role to remove (name or ID)',
         )
         domain_or_project = parser.add_mutually_exclusive_group()
         domain_or_project.add_argument(
             '--domain',
             metavar='<domain>',
-            help='Name or ID of domain associated with user or group',
+            help='Include <domain> (name or ID)',
         )
         domain_or_project.add_argument(
             '--project',
             metavar='<project>',
-            help='Name or ID of project associated with user or group',
+            help='Include <project> (name or ID)',
+        )
+        user_or_group = parser.add_mutually_exclusive_group()
+        user_or_group.add_argument(
+            '--user',
+            metavar='<user>',
+            help='Include <user> (name or ID)',
+        )
+        user_or_group.add_argument(
+            '--group',
+            metavar='<group>',
+            help='Include <group> (name or ID)',
         )
         return parser
 
@@ -431,7 +431,7 @@ class RemoveRole(command.Command):
 
 
 class SetRole(command.Command):
-    """Set role command"""
+    """Set role properties"""
 
     log = logging.getLogger(__name__ + '.SetRole')
 
@@ -440,12 +440,12 @@ class SetRole(command.Command):
         parser.add_argument(
             'role',
             metavar='<role>',
-            help='Name or ID of role to update',
+            help='Role to modify (name or ID)',
         )
         parser.add_argument(
             '--name',
-            metavar='<new-role-name>',
-            help='New role name',
+            metavar='<name>',
+            help='Set role name',
         )
         return parser
 
@@ -475,7 +475,7 @@ class ShowRole(show.ShowOne):
         parser.add_argument(
             'role',
             metavar='<role>',
-            help='Name or ID of role to display',
+            help='Role to show (name or ID)',
         )
         return parser
 
diff --git a/openstackclient/identity/v3/user.py b/openstackclient/identity/v3/user.py
index 63dd3b4f..10ffce36 100644
--- a/openstackclient/identity/v3/user.py
+++ b/openstackclient/identity/v3/user.py
@@ -37,13 +37,23 @@ class CreateUser(show.ShowOne):
         parser = super(CreateUser, self).get_parser(prog_name)
         parser.add_argument(
             'name',
-            metavar='<user-name>',
+            metavar='<name>',
             help='New user name',
         )
         parser.add_argument(
+            '--domain',
+            metavar='<domain>',
+            help='Default domain (name or ID)',
+        )
+        parser.add_argument(
+            '--project',
+            metavar='<project>',
+            help='Default project (name or ID)',
+        )
+        parser.add_argument(
             '--password',
-            metavar='<user-password>',
-            help='New user password',
+            metavar='<password>',
+            help='Set user password',
         )
         parser.add_argument(
             '--password-prompt',
@@ -53,23 +63,13 @@ class CreateUser(show.ShowOne):
         )
         parser.add_argument(
             '--email',
-            metavar='<user-email>',
-            help='New user email address',
-        )
-        parser.add_argument(
-            '--project',
-            metavar='<project>',
-            help='Set default project (name or ID)',
-        )
-        parser.add_argument(
-            '--domain',
-            metavar='<domain>',
-            help='New default domain name or ID',
+            metavar='<email-address>',
+            help='Set user email address',
         )
         parser.add_argument(
             '--description',
             metavar='<description>',
-            help='Description for new user',
+            help='User description',
         )
         enable_group = parser.add_mutually_exclusive_group()
         enable_group.add_argument(
@@ -173,12 +173,12 @@ class ListUser(lister.Lister):
         parser.add_argument(
             '--domain',
             metavar='<domain>',
-            help='Filter user list by <domain> (name or ID)',
+            help='Filter users by <domain> (name or ID)',
         )
         parser.add_argument(
             '--group',
             metavar='<group>',
-            help='List memberships of <group> (name or ID)',
+            help='Filter users by <group> membership (name or ID)',
         )
         parser.add_argument(
             '--long',
@@ -240,13 +240,23 @@ class SetUser(command.Command):
         )
         parser.add_argument(
             '--name',
-            metavar='<new-user-name>',
-            help='New user name',
+            metavar='<name>',
+            help='Set user name',
+        )
+        parser.add_argument(
+            '--domain',
+            metavar='<domain>',
+            help='Set default domain (name or ID)',
+        )
+        parser.add_argument(
+            '--project',
+            metavar='<project>',
+            help='Set default project (name or ID)',
         )
         parser.add_argument(
             '--password',
-            metavar='<user-password>',
-            help='New user password',
+            metavar='<password>',
+            help='Set user password',
         )
         parser.add_argument(
             '--password-prompt',
@@ -256,23 +266,13 @@ class SetUser(command.Command):
         )
         parser.add_argument(
             '--email',
-            metavar='<user-email>',
-            help='New user email address',
-        )
-        parser.add_argument(
-            '--domain',
-            metavar='<domain>',
-            help='New domain name or ID',
-        )
-        parser.add_argument(
-            '--project',
-            metavar='<project>',
-            help='New project name or ID',
+            metavar='<email-address>',
+            help='Set user email address',
         )
         parser.add_argument(
             '--description',
             metavar='<description>',
-            help='New description',
+            help='Set user description',
         )
         enable_group = parser.add_mutually_exclusive_group()
         enable_group.add_argument(
@@ -380,7 +380,7 @@ class ShowUser(show.ShowOne):
         parser.add_argument(
             '--domain',
             metavar='<domain>',
-            help='Domain where user resides (name or ID)',
+            help='Domain owning <user> (name or ID)',
         )
         return parser