DOCS-5902 DOCS-5903 createRole clarifications and fix parameter ordering for user/role methods

kay-kim · kay-kim · commit 15335ec7c918 · 2015-07-25T15:57:37.000-04:00
diff --git a/source/core/authorization.txt b/source/core/authorization.txt
@@ -35,13 +35,11 @@ the union of all the privileges of the respective roles.
 Roles
 -----
 
-A role consists of privileges that pair resources with allowed operations.
-Each privilege is defined directly in the role or inherited from another
-role.
+A role consists of privileges that pair resources with allowed
+operations. Each privilege is specified explicitly in the role or
+inherited from another role or both.
 
-A role's privileges apply to the database where the role is created. A role
-created on the ``admin`` database can include privileges that apply to all
-databases or to the :ref:`cluster <resource-cluster>`.
+.. include:: /includes/fact-roles-privileges-scope.rst
 
 A user assigned a role receives all the privileges of that role. The user can
 have multiple roles and can have different roles on different databases.
diff --git a/source/includes/apiargs-dbcommand-createRole-field.yaml b/source/includes/apiargs-dbcommand-createRole-field.yaml
@@ -11,9 +11,11 @@ type: string
 arg_name: field
 description: |
   The privileges to grant the role. A privilege consists of a resource
-  and permitted actions. You must specify the ``privileges`` field. Use an
-  empty array to specify *no* privileges. For the syntax of a privilege, see the
+  and permitted actions. For the syntax of a privilege, see the
   :data:`~admin.system.roles.privileges` array.
+
+  You must include the ``privileges`` field. Use an
+  empty array to specify *no* privileges. 
 interface: dbcommand
 name: privileges
 operation: createRole
@@ -23,8 +25,10 @@ type: array
 ---
 arg_name: field
 description: |
-  An array of roles from which this role inherits privileges. You must
-  specify the ``roles`` field. Use an empty array to specify *no* roles.
+  An array of roles from which this role inherits privileges.
+
+  You must include the ``roles`` field. Use an empty array to specify
+  *no* roles to inherit from.
 interface: dbcommand
 name: roles
 operation: createRole
diff --git a/source/includes/apiargs-method-db.collection.aggregate-options.yaml b/source/includes/apiargs-method-db.collection.aggregate-options.yaml
@@ -23,7 +23,7 @@ interface: method
 name: allowDiskUse
 operation: db.collection.aggregate
 optional: true
-position: 1
+position: 2
 type: boolean
 ---
 arg_name: field
diff --git a/source/includes/apiargs-method-db.createRole-param.yaml b/source/includes/apiargs-method-db.createRole-param.yaml
@@ -14,4 +14,5 @@ operation: db.createRole
 source:
   file: apiargs-dbcommand-createRole-field.yaml
   ref: writeConcern
+position: 2
 ...
diff --git a/source/includes/apiargs-method-db.createRole-role-field.yaml b/source/includes/apiargs-method-db.createRole-role-field.yaml
@@ -14,11 +14,13 @@ operation: db.createRole
 source:
   file: apiargs-dbcommand-createRole-field.yaml
   ref: privileges
+position: 2
 ---
 arg_name: field
 interface: method
 operation: db.createRole
 source:
   file: apiargs-dbcommand-createRole-field.yaml
   ref: roles
+position: 3
 ...
diff --git a/source/includes/apiargs-method-db.createUser-param.yaml b/source/includes/apiargs-method-db.createUser-param.yaml
@@ -15,4 +15,5 @@ operation: db.createUser
 source:
   file: apiargs-dbcommand-createUser-field.yaml
   ref: writeConcern
+position: 2
 ...
diff --git a/source/includes/apiargs-method-db.createUser-user-doc-param.yaml b/source/includes/apiargs-method-db.createUser-user-doc-param.yaml
@@ -14,18 +14,21 @@ operation: db.createUser
 source:
   file: apiargs-dbcommand-createUser-field.yaml
   ref: pwd
+position: 2
 ---
 arg_name: field
 interface: method
 operation: db.createUser
 source:
   file: apiargs-dbcommand-createUser-field.yaml
   ref: customData
+position: 3
 ---
 arg_name: field
 interface: method
 operation: db.createUser
 source:
   file: apiargs-dbcommand-createUser-field.yaml
   ref: roles
+position: 4
 ...
diff --git a/source/includes/apiargs-method-db.dropAllRoles-param.yaml b/source/includes/apiargs-method-db.dropAllRoles-param.yaml
@@ -3,4 +3,5 @@ operation: db.dropAllRoles
 source:
   file: apiargs-dbcommand-dropAllRolesFromDatabase-field.yaml
   ref: writeConcern
+position: 1
 ...
diff --git a/source/includes/apiargs-method-db.dropAllUsers-param.yaml b/source/includes/apiargs-method-db.dropAllUsers-param.yaml
@@ -3,4 +3,5 @@ operation: db.dropAllUsers
 source:
   file: apiargs-dbcommand-dropUser-field.yaml
   ref: writeConcern
+position: 1
 ...
diff --git a/source/includes/apiargs-method-db.dropRole-param.yaml b/source/includes/apiargs-method-db.dropRole-param.yaml
@@ -15,4 +15,5 @@ operation: db.dropRole
 source:
   file: apiargs-dbcommand-dropRole-field.yaml
   ref: writeConcern
+position: 2
 ...
diff --git a/source/includes/apiargs-method-db.dropUser-param.yaml b/source/includes/apiargs-method-db.dropUser-param.yaml
@@ -14,4 +14,5 @@ operation: db.dropUser
 source:
   file: apiargs-dbcommand-dropUser-field.yaml
   ref: writeConcern
+position: 2
 ...
diff --git a/source/includes/apiargs-method-db.getRole-param.yaml b/source/includes/apiargs-method-db.getRole-param.yaml
@@ -16,6 +16,6 @@ interface: method
 name: showPrivileges
 operation: db.getRole
 optional: true
-position: 1
+position: 2
 type: document
 ...
diff --git a/source/includes/apiargs-method-db.getRoles-field.yaml b/source/includes/apiargs-method-db.getRoles-field.yaml
@@ -14,6 +14,7 @@ operation: db.getRoles
 source:
   file: apiargs-dbcommand-rolesInfo-field.yaml
   ref: showPrivileges
+position: 2
 ---
 arg_name: field
 description: |
@@ -22,6 +23,6 @@ interface: method
 name: showBuiltinRoles
 operation: db.getRoles
 optional: true
-position: 1
+position: 3
 type: Boolean
 ...
diff --git a/source/includes/apiargs-method-db.grantPrivilegesToRole-param.yaml b/source/includes/apiargs-method-db.grantPrivilegesToRole-param.yaml
@@ -8,13 +8,15 @@ optional: false
 position: 1
 type: string
 ---
+position: 2
 arg_name: param
 interface: method
 operation: db.grantPrivilegesToRole
 source:
   file: apiargs-dbcommand-grantPrivilegesToRole-field.yaml
   ref: privileges
 ---
+position: 3
 arg_name: param
 interface: method
 operation: db.grantPrivilegesToRole
diff --git a/source/includes/apiargs-method-db.grantRolesToRole-param.yaml b/source/includes/apiargs-method-db.grantRolesToRole-param.yaml
@@ -8,13 +8,15 @@ optional: false
 position: 1
 type: string
 ---
+position: 2
 arg_name: param
 interface: method
 operation: db.grantRolesToRole
 source:
   file: apiargs-dbcommand-grantRolesToRole-field.yaml
   ref: roles
 ---
+position: 3
 arg_name: param
 interface: method
 operation: db.grantRolesToRole
diff --git a/source/includes/apiargs-method-db.grantRolesToUser-param.yaml b/source/includes/apiargs-method-db.grantRolesToUser-param.yaml
@@ -8,13 +8,15 @@ optional: false
 position: 1
 type: string
 ---
+position: 2
 arg_name: param
 interface: method
 operation: db.grantRolesToUser
 source:
   file: apiargs-dbcommand-grantRolesToUser-field.yaml
   ref: roles
 ---
+position: 3
 arg_name: param
 interface: method
 operation: db.grantRolesToUser
diff --git a/source/includes/apiargs-method-db.revokePrivilegesFromRole-param.yaml b/source/includes/apiargs-method-db.revokePrivilegesFromRole-param.yaml
@@ -9,13 +9,15 @@ optional: false
 position: 1
 type: string
 ---
+position: 2
 arg_name: param
 interface: method
 operation: db.revokePrivilegesFromRole
 source:
   file: apiargs-dbcommand-revokePrivilegesFromRole-field.yaml
   ref: privileges
 ---
+position: 3
 arg_name: param
 interface: method
 operation: db.revokePrivilegesFromRole
diff --git a/source/includes/apiargs-method-db.revokeRolesFromRole-param.yaml b/source/includes/apiargs-method-db.revokeRolesFromRole-param.yaml
@@ -8,13 +8,15 @@ optional: false
 position: 1
 type: string
 ---
+position: 2
 arg_name: param
 interface: method
 operation: db.revokeRolesFromRole
 source:
   file: apiargs-dbcommand-revokeRolesFromRole-field.yaml
   ref: roles
 ---
+position: 3
 arg_name: param
 interface: method
 operation: db.revokeRolesFromRole
diff --git a/source/includes/apiargs-method-db.revokeRolesFromUser-param.yaml b/source/includes/apiargs-method-db.revokeRolesFromUser-param.yaml
@@ -8,13 +8,15 @@ optional: false
 position: 1
 type: string
 ---
+position: 2
 arg_name: param
 interface: method
 operation: db.revokeRolesFromUser
 source:
   file: apiargs-dbcommand-revokeRolesFromUser-field.yaml
   ref: roles
 ---
+position: 3
 arg_name: param
 interface: method
 operation: db.revokeRolesFromUser
diff --git a/source/includes/apiargs-method-db.updateRole-param.yaml b/source/includes/apiargs-method-db.updateRole-param.yaml
@@ -19,6 +19,7 @@ optional: false
 position: 2
 type: document
 ---
+position: 3
 arg_name: param
 interface: method
 operation: db.updateRole
diff --git a/source/includes/apiargs-method-db.updateRole-update-fields.yaml b/source/includes/apiargs-method-db.updateRole-update-fields.yaml
@@ -1,9 +1,11 @@
+position: 1
 interface: method
 operation: db.updateRole
 source:
   file: apiargs-dbcommand-updateRole-field.yaml
   ref: privileges
 ---
+position: 2
 interface: method
 operation: db.updateRole
 source:
diff --git a/source/includes/apiargs-method-db.updateUser-param.yaml b/source/includes/apiargs-method-db.updateUser-param.yaml
@@ -19,6 +19,7 @@ optional: false
 position: 2
 type: document
 ---
+position: 3
 arg_name: param
 interface: method
 operation: db.updateUser
diff --git a/source/includes/apiargs-method-db.updateUser-update-fields.yaml b/source/includes/apiargs-method-db.updateUser-update-fields.yaml
@@ -1,15 +1,18 @@
+position: 1
 interface: method
 operation: db.updateUser
 source:
   file: apiargs-dbcommand-updateUser-field.yaml
   ref: customData
 ---
+position: 2
 interface: method
 operation: db.updateUser
 source:
   file: apiargs-dbcommand-updateUser-field.yaml
   ref: roles
 ---
+position: 3
 interface: method
 operation: db.updateUser
 source:
diff --git a/source/includes/apiargs-method-db.upgradeCheck-param.yaml b/source/includes/apiargs-method-db.upgradeCheck-param.yaml
@@ -1,5 +1,5 @@
 arg_name: param
-description: |2
+description: |
 
   Document to limit the scope of the check to the specified collection
   in the database.
diff --git a/source/includes/apiargs-method-load-param.yaml b/source/includes/apiargs-method-load-param.yaml
@@ -1,10 +1,10 @@
 arg_name: param
-description: |-
+description: |
   Specifies the path of a JavaScript file to execute.
 interface: method
 name: filename
 operation: load
 optional: false
-position: 2
+position: 1
 type: string
 ...
diff --git a/source/includes/fact-roles-privileges-scope.rst b/source/includes/fact-roles-privileges-scope.rst
@@ -0,0 +1,8 @@
+Except for roles created in the ``admin`` database, a role can only
+include privileges that apply to its database and can only inherit from
+other roles in its database.
+
+A role created in the ``admin`` database can include privileges that
+apply to the ``admin`` database, other databases or to the
+:ref:`cluster <resource-cluster>` resource, and can inherit from roles
+in other databases as well as the ``admin`` database.
diff --git a/source/reference/method/db.createRole.txt b/source/reference/method/db.createRole.txt
@@ -9,11 +9,10 @@ Definition
 
 .. method:: db.createRole ( role, writeConcern )
 
-   Creates a role and specifies its :ref:`privileges <privileges>`.
-   The role applies to the
-   database on which you run the method. The :method:`db.createRole()`
-   method returns a *duplicate role* error if the role already exists in the
-   database.
+   Creates a role in a database. You can specify privileges for the
+   role by explicitly listing the privileges or by having the role
+   inherit privileges from other roles or both. The role applies to
+   the database on which you run the method.
 
    The :method:`db.createRole()` method takes the following arguments:
 
@@ -23,7 +22,8 @@ Definition
 
    .. code-block:: javascript
 
-      { role: "<name>",
+      {
+        role: "<name>",
         privileges: [
            { resource: { <resource> }, actions: [ "<action>", ... ] },
            ...
@@ -47,11 +47,12 @@ Definition
 Behavior
 --------
 
-A role's privileges apply to the database where the role is created. The
-role can inherit privileges from other roles in its database. A role
-created on the ``admin`` database can include privileges that apply to all
-databases or to the :ref:`cluster <resource-cluster>` and can inherit
-privileges from roles in other databases.
+.. include:: /includes/fact-roles-privileges-scope.rst
+
+
+
+The :method:`db.createRole()` method returns a *duplicate role* error
+if the role already exists in the database.
 
 Required Access
 ---------------
@@ -67,15 +68,18 @@ The following :method:`db.createRole()` method creates the
 .. code-block:: javascript
 
    use admin
-   db.createRole({ role: "myClusterwideAdmin",
-     privileges: [
-       { resource: { cluster: true }, actions: [ "addShard" ] },
-       { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert", "remove" ] },
-       { resource: { db: "users", collection: "usersCollection" }, actions: [ "update", "insert", "remove" ] },
-       { resource: { db: "", collection: "" }, actions: [ "find" ] }
-     ],
-     roles: [
-       { role: "read", db: "admin" }
-     ],
-     writeConcern: { w: "majority" , wtimeout: 5000 }
-   })
+   db.createRole(
+      {
+        role: "myClusterwideAdmin",
+        privileges: [
+          { resource: { cluster: true }, actions: [ "addShard" ] },
+          { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert", "remove" ] },
+          { resource: { db: "users", collection: "usersCollection" }, actions: [ "update", "insert", "remove" ] },
+          { resource: { db: "", collection: "" }, actions: [ "find" ] }
+        ],
+        roles: [
+          { role: "read", db: "admin" }
+        ]
+      },
+      { w: "majority" , wtimeout: 5000 }
+   )
diff --git a/source/reference/method/db.grantPrivilegesToRole.txt b/source/reference/method/db.grantPrivilegesToRole.txt
diff --git a/source/reference/method/db.updateRole.txt b/source/reference/method/db.updateRole.txt
