fixes to user & role reference docs

source/reference/command/createRole-field.yaml

@@ -34,7 +34,10 @@ name: roles
 type: array
 position: 3
 description: |
-  Roles from which this role inherits privileges.
+  Roles from which this role inherits privileges. You can specify both
+  :ref:`system-defined roles <system-user-roles>` and :ref:`user-defined
+  role <user-defined-roles>`. For the syntax of a role, see the
+  :data:`~admin.system.roles.roles` array.
 ---
 object:
   name: createRole

source/reference/command/createRole.txt

@@ -34,25 +34,9 @@ Definition
 
    .. include:: /reference/command/createRole-field.rst
 
-.. TODO rename section (or make it subsection or something)
-
-Considerations
---------------
-
-``privileges`` Field
-~~~~~~~~~~~~~~~~~~~~
-
-The ``privileges`` field must be present. If you choose not to specify
-privileges, you must provide an empty array.
-
-``roles`` Field
-~~~~~~~~~~~~~~~
-
-The ``roles`` fields must be present. If you choose not to specify
-any roles, you must provide an empty array.
-
-.. |local-cmd-name| replace:: :dbcommand:`createRole`
-.. include:: /includes/fact-roles-array-contents.rst
+   .. important:: Both the ``privileges`` array and ``roles`` array must be
+      present. If you choose not to specify one or the other, or both, you
+      must provide empty arrays.
 
 Required Access
 ---------------

source/reference/command/createUser-field.yaml

@@ -21,10 +21,14 @@ name: pwd
 type: string
 position: 2
 description: |
-  The user's password. The ``pwd`` field is not
-  required if you run |local-cmd-name| on the ``$external``
-  database to create users who have credentials stored externally to
-  MongoDB. See :ref:`createUser-pwd-field-consideration`.
+  The user's password. The command sends the password to the MongoDB
+  instance in cleartext. To encrypt the password in transit, use :doc:`SSL
+  </tutorial/configure-ssl>`. The ``pwd`` field is not required if you run
+  this command on the ``$external`` database. Users created on the
+  ``$external`` database should have credentials stored externally to
+  MongoDB, as, for example, with :doc:`MongoDB Enterprise installations that
+  use Kerberos
+  </tutorial/control-access-to-mongodb-with-kerberos-authentication>`.
 ---
 object:
   name: createUser
@@ -48,7 +52,10 @@ name: roles
 type: array
 position: 4
 description: |
-  The roles granted to the user.
+  The roles granted to the user. You can specify both :ref:`system-defined
+  roles <system-user-roles>` and :ref:`user-defined role
+  <user-defined-roles>`. For the syntax of a role, see the
+  :data:`~admin.system.users.roles` array.
 ---
 object:
   name: createUser

source/reference/command/createUser.txt

@@ -31,30 +31,6 @@ Definition
    .. |local-cmd-name| replace:: :dbcommand:`createUser`
    .. include:: /reference/command/createUser-field.rst
 
-.. TODO rename section (or make it subsection or something)
-
-Considerations
---------------
-
-.. _createUser-pwd-field-consideration:
-
-``pwd`` Field
-~~~~~~~~~~~~~
-
-:dbcommand:`createUser` sends password to the MongoDB instance in
-cleartext. To encrypt the password in transit, use :doc:`SSL
-</tutorial/configure-ssl>`.
-
-Users created on the ``$external`` database should have credentials
-stored externally to MongoDB, as, for example, with :doc:`MongoDB
-Enterprise installations that use Kerberos
-</tutorial/control-access-to-mongodb-with-kerberos-authentication>`.
-
-``roles`` Field
-~~~~~~~~~~~~~~~
-
-.. include:: /includes/fact-roles-array-contents.rst
-
 Required Access
 ---------------
 

source/reference/command/grantRolesToRole-field.yaml

@@ -20,7 +20,10 @@ name: roles
 type: array
 position: 2
 description: |
-  An array of roles from which to inherit.
+  An array of roles from which to inherit privileges. You can specify both
+  :ref:`system-defined roles <system-user-roles>` and :ref:`user-defined
+  role <user-defined-roles>`. For the syntax of a role, see the
+  :data:`~admin.system.roles.roles` array.
 ---
 object:
   name: grantRolesToRole

source/reference/command/grantRolesToRole.txt

@@ -29,14 +29,6 @@ Definition
 
    .. include:: /reference/command/grantRolesToRole-field.rst
 
-.. TODO rename section (or make it subsection or something)
-
-Considerations
---------------
-
-.. |local-cmd-name| replace:: :dbcommand:`grantRolesToRole`
-.. include:: /includes/fact-roles-array-contents.rst
-
 Required Access
 ---------------
 

source/reference/command/grantRolesToUser-field.yaml

@@ -20,7 +20,10 @@ name: roles
 type: array
 position: 2
 description: |
-  An array of additional roles to grant to the user.
+  An array of additional roles to grant to the user. You can specify both
+  :ref:`system-defined roles <system-user-roles>` and :ref:`user-defined
+  role <user-defined-roles>`. For the syntax of a role, see the
+  :data:`~admin.system.users.roles` array.
 ---
 object:
   name: grantRolesToUser

source/reference/command/grantRolesToUser.txt

@@ -26,14 +26,6 @@ Definition
 
    .. include:: /reference/command/grantRolesToUser-field.rst
 
-.. TODO rename section (or make it subsection or something)
-
-Considerations
---------------
-
-.. |local-cmd-name| replace:: :dbcommand:`grantRolesToUser`
-.. include:: /includes/fact-roles-array-contents.rst
-
 Required Access
 ---------------
 

source/reference/command/revokeRolesFromRole-field.yaml

@@ -20,7 +20,8 @@ name: roles
 type: array
 position: 2
 description: |
-  The inherited roles to remove.
+  The inherited roles to remove. For the syntax of a role, see the
+  :data:`~admin.system.roles.roles` array.
 ---
 object:
   name: revokeRolesFromRole

source/reference/command/revokeRolesFromRole.txt

@@ -26,9 +26,6 @@ Definition
 
    .. include:: /reference/command/revokeRolesFromRole-field.rst
 
-   .. |local-cmd-name| replace:: :dbcommand:`revokeRolesFromRole`
-   .. include:: /includes/fact-roles-array-contents.rst
-
 Required Access
 ---------------
 

source/reference/command/revokeRolesFromUser-field.yaml

@@ -20,7 +20,10 @@ name: roles
 type: array
 position: 2
 description: |
-  The roles to remove from the user.
+  The roles to remove from the user. You can specify both
+  :ref:`system-defined roles <system-user-roles>` and :ref:`user-defined
+  role <user-defined-roles>`. For the syntax of a role, see the
+  :data:`~admin.system.users.roles` array.
 ---
 object:
   name: revokeRolesFromUser

source/reference/command/revokeRolesFromUser.txt

@@ -27,14 +27,6 @@ Definition
 
    .. include:: /reference/command/revokeRolesFromUser-field.rst
 
-.. TODO rename section (or something)
-
-Considerations
---------------
-
-.. |local-cmd-name| replace:: :dbcommand:`revokeRolesFromUser`
-.. include:: /includes/fact-roles-array-contents.rst
-
 Required Access
 ---------------
 

source/reference/command/updateRole-field.yaml

@@ -36,9 +36,10 @@ name: roles
 type: array
 position: 3
 description: |
-  Required if you do not specify :data:`~admin.system.roles.privileges` array.
-  The roles from which this role inherits privileges. An update to the
-  ``roles`` array overrides the previous array's values.
+  Required if you do not specify :data:`~admin.system.roles.privileges`
+  array. The roles from which this role inherits privileges. An update to
+  the ``roles`` array overrides the previous array's values. For the syntax
+  of a role, see the :data:`~admin.system.roles.roles` array.
 ---
 object:
   name: updateRole

source/reference/command/updateRole.txt

@@ -41,12 +41,6 @@ Definition
 
    .. include:: /reference/command/updateRole-field.rst
 
-``roles`` Field
----------------
-
-.. |local-cmd-name| replace:: :dbcommand:`updateRole`
-.. include:: /includes/fact-roles-array-contents.rst
-
 Required Access
 ---------------
 

source/reference/command/updateUser-field.yaml

@@ -20,7 +20,9 @@ name: pwd
 type: string
 position: 2
 description: |
-  The user's password. See :ref:`updateUser-pwd-field-consideration`.
+  The user's password. :dbcommand:`updateUser` sends the password to the
+  MongoDB instance in cleartext. To encrypt the password in transit, use
+  :doc:`SSL </tutorial/configure-ssl>`
 ---
 object:
   name: updateUser
@@ -44,8 +46,11 @@ name: roles
 type: array
 position: 4
 description: |
-  The roles granted to the user. An update to the ``roles`` array
-  overrides the previous array's values. 
+  The roles granted to the user. An update to the ``roles`` array overrides
+  the previous array's values. You can specify both :ref:`system-defined
+  roles <system-user-roles>` and :ref:`user-defined role
+  <user-defined-roles>`. For the syntax of a role, see the
+  :data:`~admin.system.users.roles` array.
 ---
 object:
   name: updateUser

source/reference/command/updateUser.txt

@@ -39,24 +39,6 @@ Definition
 
    .. include:: /reference/command/updateUser-field.rst
 
-Considerations
---------------
-
-.. _updateUser-pwd-field-consideration:
-
-``pwd`` Field
-~~~~~~~~~~~~~
-
-:dbcommand:`updateUser` sends password to the MongoDB instance in
-cleartext. To encrypt the password in transit, use :doc:`SSL
-</tutorial/configure-ssl>`.
-
-``roles`` Field
-~~~~~~~~~~~~~~~
-
-.. |local-cmd-name| replace:: :dbcommand:`updateUser`
-.. include:: /includes/fact-roles-array-contents.rst
-
 Required Access
 ---------------
 

source/reference/method/db.addUser.txt

@@ -48,9 +48,6 @@ Definition
    installations that use Kerberos
    </tutorial/control-access-to-mongodb-with-kerberos-authentication>`.
 
-   .. |local-cmd-name| replace:: :method:`db.addUser()`
-   .. include:: /includes/fact-roles-array-contents.rst
-
 .. note::
 
    In 2.5.3, MongoDB introduced a new model for user

source/reference/system-roles-collection.txt

@@ -81,9 +81,12 @@ A ``system.roles`` document has the following fields:
 
 .. data:: admin.system.roles.roles
 
-   The :data:`~admin.system.roles.roles` array contains role documents
-   that specify the roles from which this role inherits privileges. A
-   role document has the following syntax:
+   The :data:`~admin.system.roles.roles` array contains role documents that
+   specify the roles from which this role inherits privileges. The array can
+   specify both :ref:`system-defined roles <system-user-roles>` and
+   :ref:`user-defined role <user-defined-roles>`.
+
+   A role document has the following syntax:
 
    .. code-block:: javascript
 
@@ -101,6 +104,12 @@ A ``system.roles`` document has the following fields:
 
       The name of the database where the role is defined.
 
+   When using :ref:`role-management commands <role-management-commands>` or
+   :ref:`user-management commands <user-management-commands>` to add a role
+   to the :data:`~admin.system.roles.roles` array, you can specify the role
+   with just the role name (e.g. ``"readWrite"``) if the role that exists
+   on the database on which the command is run.
+
 Examples
 --------
 

source/reference/system-users-collection.txt

@@ -63,9 +63,12 @@ Each ``system.users`` document has the following fields:
 
 .. data:: admin.system.users.roles
 
-   The :data:`~admin.system.users.roles` array contains role documents
-   that specify the roles granted to the user. Each role document has
-   the following syntax:
+   The :data:`~admin.system.users.roles` array contains role documents that
+   specify the roles granted to the user. The array can specify both
+   :ref:`system-defined roles <system-user-roles>` and :ref:`user-defined
+   role <user-defined-roles>`.
+
+   A role document has the following syntax:
 
    .. code-block:: javascript
 
@@ -83,6 +86,12 @@ Each ``system.users`` document has the following fields:
 
       The name of the database where role is defined.
 
+   When using :ref:`role-management commands <role-management-commands>` or
+   :ref:`user-management commands <user-management-commands>` to add a role
+   to the :data:`~admin.system.users.roles` array, you can specify the role
+   with just the role name (e.g. ``"readWrite"``) if the role that exists
+   on the database on which the command is run.
+
 .. data:: admin.system.users.customData
 
    The :data:`~admin.system.users.customData` field contains optional