DOCS-2243 add getRole and getRoles methods

bin/builddata/htaccess-next.yaml

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

source/includes/access-roles-info.rst

@@ -0,0 +1,2 @@
+To view role information, a user must have privileges that contain the
+:authaction:`viewRole` action on the database where the role exists.

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

@@ -37,14 +37,14 @@ name: :method:`db.revokeRolesFromRole()`
 file: /reference/method/db.revokeRolesFromRole
 description: |
   Removes a role from a user.
-# ---
-# name: :method:`db.getRole()`
-# file: /reference/method/db.getRole
-# description: |
-#   Returns information for the specified role.
-# ---
-# name: :method:`db.getRoles()`
-# file: /reference/method/db.getRoles
-# description: |
-#   Returns information for all the user-defined roles in a database.
+---
+name: :method:`db.getRole()`
+file: /reference/method/db.getRole
+description: |
+  Returns information for the specified role.
+---
+name: :method:`db.getRoles()`
+file: /reference/method/db.getRoles
+description: |
+  Returns information for all the user-defined roles in a database.
 ...

source/reference/command/dropAllUsersFromDatabase.txt

@@ -33,6 +33,8 @@ Definition
 Required Access
 ---------------
 
+.. |local-cmd-name| replace:: :command:`dropAllUsersFromDatabase`
+
 .. include:: /includes/access-drop-all-users.rst
 
 Example

source/reference/command/dropUser.txt

@@ -27,6 +27,8 @@ Definition
 Required Access
 ---------------
 
+.. |local-cmd-name| replace:: :command:`dropUser`
+
 .. include:: /includes/access-drop-user.rst
 
 Example

source/reference/command/rolesInfo-field.yaml

@@ -5,13 +5,15 @@ field:
   optional: false
   type: field
 name: rolesInfo
-type: various
+type:
+    - string
+    - document
+    - array
+    - integer
 position: 1
 description: |
   The role(s) to return information about.
-  See :ref:`rolesInfo-field-specification`.
 ---
-
 object:
   name: rolesInfo
   type: dbcommand

source/reference/command/rolesInfo.txt

@@ -15,41 +15,30 @@ Definition
 
    .. include:: /reference/command/rolesInfo-field.rst
 
-.. _rolesInfo-field-specification:
-
-``rolesInfo`` Field Specification
----------------------------------
-
-Specify a Single Role
-~~~~~~~~~~~~~~~~~~~~~
-
-In the ``rolesInfo`` field, specify a document with the role's name and
-database:
+To specify a single role, specify the role by a document that includes the
+role's name and database:
 
 .. code-block:: javascript
 
-   rolesInfo: { role: <name>, db: <db> }
+   rolesInfo: { role: "<rolename>", db: "<database>" }
 
-Alternatively, for a role that exists on the same database that the
-command is run, you can specify the role by name only.
+Alternately, if the role exists in the database on which the command runs,
+you can instead specify the role just by its name:
 
 .. code-block:: javascript
+
+   rolesInfo: "<rolename>"
 
-   rolesInfo: "<name>"
-
-Specify Multiple Roles
-~~~~~~~~~~~~~~~~~~~~~~
-
-In the ``rolesInfo`` field, specify an array of documents:
+To specify multiple roles, specify an array of roles. Specify each role in
+the array as a document or string. Use a string only if the role exists on
+the database on which the command runs:
 
 .. code-block:: javascript
 
-   rolesInfo: [ { role: <name>, db: <db> }, { role: <name>, db: <db> }, ... ]
-
-Specify All Roles for a Database
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   rolesInfo: [ "<rolename1>", { role: "<rolename2>", db: "<database>" }, { role: "<rolename3>", db: "<database>" }, ... ]
 
-In the ``rolesInfo`` field, specify ``1``:
+To specify all roles in the database on which the command runs, specify
+``1``:
 
 .. code-block:: javascript
 
@@ -58,8 +47,7 @@ In the ``rolesInfo`` field, specify ``1``:
 Required Access
 ---------------
 
-To view role information, a user must have privileges that contain the
-:authaction:`viewRole` action on the database where the role exists. 
+.. include:: /includes/access-roles-info.rst
 
 Examples
 --------

source/reference/command/updateUser-field.yaml

@@ -1,6 +1,6 @@
 #content from this file is included in /reference/method/db.updateUser-param.yaml
 #content from this file is included in /reference/method/db.updateUser-doc-field.yaml
- object:
+object:
   name: updateUser
   type: dbcommand
 field:

source/reference/method/db.dropUser.txt

@@ -18,11 +18,11 @@ Definition
    The :method:`db.dropUser()` method wraps the :dbcommand:`dropUser`
    command.
 
-   .. |local-cmd-name| replace:: :method:`db.dropUser()`
-
 Required Access
 ---------------
 
+.. |local-cmd-name| replace:: :method:`db.dropUser()`
+
 .. include:: /includes/access-drop-user.rst
 
 Example

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

@@ -0,0 +1,12 @@
+object:
+  name: db.getRole()
+  type: method
+field:
+  optional: false
+  type: param
+name: rolename
+type: string
+position: 1
+description: |
+  The name of the role for which to retrieve information.
+...

source/reference/method/db.getRole.txt

@@ -0,0 +1,35 @@
+============
+db.getRole()
+============
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.getRole(rolename)
+
+   Returns information for a specified role. Run this method on the database
+   that contains the role.
+
+   The :method:`db.getRole()` method has the following parameter:
+
+   .. include:: /reference/method/db.getRole-param.rst
+
+   :method:`db.getRole()` wraps the :dbcommand:`rolesInfo` command.
+
+Required Access
+---------------
+
+.. include:: /includes/access-roles-info.rst
+
+Example
+-------
+
+The following operation returns role information for the role ``associate``
+defined on the ``products`` database:
+
+.. code-block:: javascript
+
+   use products
+   db.getRole( "associate" )

source/reference/method/db.getRoles.txt

@@ -0,0 +1,19 @@
+=============
+db.getRoles()
+=============
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.getRoles()
+
+   Returns information for all the roles in the database.
+
+   :method:`db.getRoles()` wraps the :dbcommand:`rolesInfo` command.
+
+Required Access
+---------------
+
+.. include:: /includes/access-roles-info.rst

source/reference/method/db.updateUser.txt

@@ -42,7 +42,7 @@ Definition
    The <update document> has the following fields:
 
    .. |local-cmd-name| replace:: :method:`db.updateUser()`
-   .. include:: /reference/method/db.updateUser-doc-field.rst
+   .. include:: /reference/command/db.updateUser-field.rst
 
    .. include:: /includes/fact-roles-array-contents.rst