minor changes

bin/builddata/htaccess-next.yaml

@@ -585,6 +585,14 @@ redirect-path: '/reference/method/db.getUsers'
 url-base: '/reference/security'
 type: 'redirect'
 code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/reference/method/db.updateRole'
+url-base: '/reference/security'
+type: 'redirect'
+code: 303
 outputs:
   - 'manual'
   - 'before-v2.4'

source/includes/access-update-role.rst

@@ -0,0 +1,18 @@
+A user must have the :authaction:`revokeRole` :ref:`action
+<security-user-actions>` on all databases in order to update a role.
+
+A user must have the :authaction:`grantRole` :ref:`action
+<security-user-actions>` on the database of each role in the ``roles`` array
+to update the array.
+
+A user must have the :authaction:`grantRole` action on the database of each
+privilege in the ``privileges`` array to update the array. If a privilege's
+resource spans databases, the user must have :authaction:`grantRole` on the
+``admin`` database. A privilege spans databases if the privilege is any of
+the following:
+
+- a collection in all databases
+
+- all collections and all database
+
+- the ``cluster`` resource

source/includes/ref-toc-method-role-management.yaml

@@ -3,11 +3,11 @@
 # description: |
 #   Creates a role and specifies its privileges.
 # ---
-# name: :method:`db.updateRole()`
-# file: /reference/method/db.updateRole
-# description: |
-#   Updates a user-defined role.
-# ---
+name: :method:`db.updateRole()`
+file: /reference/method/db.updateRole
+description: |
+  Updates a user-defined role.
+---
 # name: :method:`db.dropRole()`
 # file: /reference/method/db.dropRole
 # description: |

source/reference/command/updateRole.txt

@@ -47,20 +47,7 @@ Definition
 Required Access
 ---------------
 
-To run the :dbcommand:`updateRole` command, a user must have privileges
-that include the :authaction:`revokeRole` action on all databases,
-as well as:
-
-- To update the ``roles`` array, a user must have privileges that
-  include the :authaction:`grantRole` action on the database for
-  every role in the updated array.
-
-- To update the ``privileges`` array, a user must have
-  :authaction:`grantRole` on the database for each privilege in the
-  updated array. If the resource for the privilege is a collection in
-  all databases, or all collections and all database, or the
-  ``cluster`` resource, you must have :authaction:`grantRole` on
-  the ``admin`` database.
+.. include:: /includes/access-update-role.rst
 
 Example
 -------

source/reference/method/db.updateRole-param.yaml

@@ -0,0 +1,28 @@
+object:
+  name: db.updateRole()
+  type: method
+field:
+  optional: false
+  type: param
+name: rolename
+type: string
+position: 1
+description: |
+  The name of the role to update.
+---
+object:
+  name: db.updateRole()
+  type: method
+field:
+  optional: false
+  type: param
+name: update
+type: document
+position: 2
+description: |
+  A document containing the role data to replace with new data.
+---
+file: /reference/command/updateRole-field.yaml
+name: writeConcern
+position: 3
+...

source/reference/method/db.updateRole.txt

@@ -0,0 +1,60 @@
+===============
+db.updateRole()
+===============
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.updateRole( rolename, update, writeConcern )
+
+   Updates the role's profile on the database on which you run the method.
+   An update to a field **completely replaces** the previous field's values.
+   This includes updates to the role's ``roles`` array.
+
+   .. warning::
+
+      When you update the ``roles`` array, you completely replace the
+      previous array's values. To add or remove roles without replacing all
+      the role's existing roles, use the :method:`db.grantRolesToRole()` or
+      :method:`db.revokeRolesFromRole()` methods.
+
+   The :method:`db.updateRole()` method has the following arguments.
+
+   . include:: /reference/method/db.updateRole-param.rst
+
+   The ``update`` document specifies the fields to update and their
+   new values. All  fields in the ``update`` document are optional,
+   but the method document must include at least one field.
+
+   The ``update`` document has the following structure:
+
+   .. code-block:: javascript
+
+      { customData: { <any information> },
+        roles: [
+          { role: "<role>", db: "<database>" } | "<role>",
+          { ... },
+        ]
+      }
+
+   The ``update`` documehas the following fields:
+
+   .. include:: /reference/method/db.updateRole-update-fields.rst
+
+   .. |local-cmd-name| replace:: :method:`db.updateRole()`
+   .. include:: /includes/fact-roles-array-contents.rst
+
+   The :method:`db.updateRole()` method wraps the :dbcommand:`updateRole`
+   command.
+
+
+Required Access
+---------------
+
+.. include:: /includes/access-update-role.rst
+
+Example
+-------
+

source/reference/privilege-actions.txt

@@ -6,6 +6,9 @@ Privilege Actions
 
 .. default-domain:: mongodb
 
+Privilege actions, or simply "actions," are used to define the privileges
+found in roles.
+
 MongoDB uses role-based authorization to give users access to data and
 commands. Roles provide privileges to users, where privileges specify
 the actions permitted on a :ref:`resource <resource-document>`. This

source/reference/system-roles-collection.txt

@@ -69,10 +69,14 @@ A ``system.roles`` document has the following fields:
 
    .. data:: admin.system.roles.privileges[n].resource
 
-      A document that specifies the resources upon which the
-      :data:`~admin.system.roles.privileges[n].actions` for the
-      privilege applies. For the document's syntax and rules, see
-      :ref:`resource-document`.
+      A document that specifies the resources upon which the privilege
+      :data:`~admin.system.roles.privileges[n].actions` apply. The document
+      has the following form, as described further in
+      :ref:`resource-document`:
+
+      .. code-block:: javascript
+
+        { db: <database>, collection: <collection> }
 
    .. data:: admin.system.roles.privileges[n].actions