mongodb · bgrabar · Dec 2, 2013
diff --git a/source/reference/command/createUser-field.yaml b/source/reference/command/createUser-field.yaml
@@ -1,4 +1,3 @@
-#content from this page is included in /reference/method/db.addUser-param.yaml
 #content from this page is included in /reference/method/db.createUser-param.yaml
 object:
   name: createUser

diff --git a/source/reference/command/createUser.txt b/source/reference/command/createUser.txt
@@ -18,7 +18,8 @@ Definition
 
    .. code-block:: javascript
 
-      { createUser: "<name>",
+      {
+        createUser: "<name>",
         pwd: "<cleartext password>",
         customData: { <any information> },
         roles: [
@@ -34,12 +35,10 @@ Definition
 
    .. include:: /includes/fact-roles-array-contents.rst
 
-.. TODO rename section (or make it subsection or something)
-
 .. _createUser-pwd-field-consideration:
 
-Considerations
---------------
+Behavior
+--------
 
 :dbcommand:`createUser` sends password to the MongoDB instance in
 cleartext. To encrypt the password in transit, use :doc:`SSL
@@ -65,13 +64,22 @@ and the ``readWrite`` role on the ``products`` database:
 
 .. code-block:: javascript
 
-   db.getSiblingDB("products").runCommand( { createUser: "accountAdmin01",
-                                             pwd: "cleartext password",
-                                             customData: { employeeId: 12345 },
-                                             roles: [
-                                                      { role: "clusterAdmin", db: "admin" },
-                                                      { role: "readAnyDatabase", db: "admin" },
-                                                      "readWrite"
-                                                    ],
-                                             writeConcern: { w: "majority" , wtimeout: 5000 }
-                                          } )
+   use products
+   db.runCommand(
+       {
+         createUser: "accountAdmin01",
+         pwd: "cleartext password",
+         customData: { employeeId: 12345 },
+         roles:
+           [
+               {
+                 role: "clusterAdmin", db: "admin"
+               },
+               {
+                 role: "readAnyDatabase", db: "admin"
+               },
+               "readWrite"
+           ],
+         writeConcern: { w: "majority" }
+       }
+   )
diff --git a/source/reference/method/db.addUser-param-2.2.yaml b/source/reference/method/db.addUser-param-2.2.yaml
diff --git a/source/reference/method/db.addUser-param.yaml b/source/reference/method/db.addUser-param.yaml
diff --git a/source/reference/method/db.addUser.txt b/source/reference/method/db.addUser.txt
@@ -4,78 +4,11 @@ db.addUser()
 
 .. default-domain:: mongodb
 
-.. versionchanged:: 2.5.3
+.. deprecated:: 2.5.3
 
-Definition
-----------
+   MongoDB 2.5.3 introduced a new model for user management and a new method
+   for adding a user, the :method:`db.createUser()` method. Please see
+   :doc:`/reference/method/db.createUser`.
 
-.. method:: db.addUser(document)
-
-   Adds a new user on the database where you run the method. The
-   :method:`db.addUser()` method returns a *duplicate user* error if the user
-   exists.
-
-   The :method:`db.addUser()` method takes a user document as its argument:
-
-   .. code-block:: javascript
-
-      db.addUser(<user document>)
-
-   The :method:`db.addUser()` user document has the following form:
-
-   .. code-block:: javascript
-
-      { user: "<name>",
-        pwd: "<cleartext password>",
-        customData: { <any information> },
-        roles: [
-          { role: "<role>", db: "<database>" } | "<role>",
-          ...
-        ],
-        writeConcern: { <write concern> }
-      }
-
-   The :method:`db.addUser()` user document has the following fields:
-
-   .. include:: /reference/method/db.addUser-param.rst
-
-   :method:`db.addUser()` 
-   sends password to the MongoDB instance as 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>`.
-
-   .. |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
-   credentials and privileges, as described in
-   :doc:`/core/access-control`. To use :method:`db.addUser()` on MongoDB
-   2.4, see :v2.4:`db.addUser() in the v2.4 Manual
-   </reference/method/db.addUser>`.
-
-Example
--------
-
-The following :method:`db.addUser()` method creates a user ``Carlos`` on the
-database where the command runs. The command gives ``Carlos`` the
-``clusterAdmin`` and ``readAnyDatabase`` roles on the ``admin`` database
-and the ``readWrite`` role on the current database:
-
-.. code-block:: javascript
-
-   { user: "Carlos",
-     pwd: "cleartext password",
-     customData: { employeeId: 12345 },
-     roles: [
-       { role: "clusterAdmin", db: "admin" },
-       { role: "readAnyDatabase", db: "admin" },
-       "readWrite"
-     ],
-     writeConcern: { w: "majority" , wtimeout: 5000 }
-   }
+For information on the deprecated ``db.addUser()`` method, see
+:v2.4:`db.addUser() </reference/method/db.addUser>`.
diff --git a/source/reference/method/db.createUser.txt b/source/reference/method/db.createUser.txt
@@ -4,89 +4,76 @@ db.createUser()
 
 .. default-domain:: mongodb
 
+.. versionchanged:: 2.5.3
+
 Definition
 ----------
 
-.. method:: db.createUser ( user, writeConcern )
-
-   Creates a new user for the database where the method runs. :method:`db.createUser()`
-   returns a *duplicate user* error if the user already exists on the database.
+.. method:: db.createUser( userDocument, writeConcern )
 
-   :method:`db.createUser()` takes and ``user`` document and
-   the optional ``writeConcern`` document as arguments.
+   Adds a new user on the database where the method runs. The
+   :method:`db.createUser()` method returns a *duplicate user* error if the
+   user already exists.
 
-   The ``user`` document defines the user and has the following form:
+   The :method:`db.createUser()` method takes a ``userDocument`` and a
+   :doc:`writeConcern </reference/write-concern>` document as its arguments.
+   The ``userDocument`` has the following form:
 
    .. code-block:: javascript
 
-      { user: "<name>",
+      {
+        user: "<username>",
         pwd: "<cleartext password>",
         customData: { <any information> },
-        roles: [
-          { role: "<role>", db: "<database>" } | "<role>",
-          ...
-        ]
+        roles:
+          [
+            <role>,
+            ...
+          ]
       }
 
-   The ``user`` document has the following fields:
+   The ``userDocument`` has the following fields:
 
-   .. |local-cmd-name| replace:: :method:`db.createUser()`
    .. include:: /reference/method/db.createUser-param.rst
 
-   .. include:: /includes/fact-roles-array-contents.rst
-
-   The ``writeConcern`` document is optional and determines the level of
-   :doc:`write concern </reference/write-concern>` for the
-   :method:`db.createUser()` operation. The ``writeConcern`` document takes
-   the same fields as the :dbcommand:`getLastError` command.
-
-   The :method:`db.createUser()` method wraps the :dbcommand:`createUser`
-   command.
-
-Considerations
---------------
-
-Encryption
-~~~~~~~~~~
+   :method:`db.createUser()` sends password to the MongoDB instance as
+   cleartext. To encrypt the password in transit use :doc:`SSL
+   </tutorial/configure-ssl>`.
 
-:method:`db.createUser()` sends password to the MongoDB instance
-*without* encryption. To encrypt the password during transmission,
-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>`.
 
-External Credentials
-~~~~~~~~~~~~~~~~~~~~
+   The ``writeConcern`` document specifies the level of :doc:`write concern
+   </reference/write-concern>` for the creation operation. The
+   ``writeConcern`` document takes the same fields as the
+   :dbcommand:`getLastError` command.
 
-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>`.
-
-Required Access
----------------
-
-.. include:: /includes/access-create-user.rst
+   .. |local-cmd-name| replace:: :method:`db.createUser()`
+   .. include:: /includes/fact-roles-array-contents.rst
 
 Example
 -------
 
-The following :method:`db.createUser()` operation creates the
-``accountAdmin01`` user on the ``products`` database.
+The following :method:`db.createUser()` method adds the user
+``accountAdmin01`` to the database where the command runs. The command gives
+``accountAdmin01`` the ``clusterAdmin`` and ``readAnyDatabase`` roles on the
+``admin`` database and the ``readWrite`` role on the current database:
 
 .. code-block:: javascript
 
-   use products
-   db.createUser( { "user" : "accountAdmin01",
-                    "pwd": "cleartext password",
-                    "customData" : { employeeId: 12345 },
-                    "roles" : [ { role: "clusterAdmin", db: "admin" },
-                                { role: "readAnyDatabase", db: "admin" },
-                                "readWrite"
-                                ] },
-                  { w: "majority" , wtimeout: 5000 } )
-
-The operation gives ``accountAdmin01`` the following roles:
-
-- the ``clusterAdmin`` and ``readAnyDatabase`` roles on the ``admin``
-  database
-
-- the ``readWrite`` role on the ``products`` database
+   db.createUser(
+     {
+       user: "accountAdmin01",
+       pwd: "cleartext password",
+       customData: { employeeId: 12345 },
+       roles:
+         [
+           { role: "clusterAdmin", db: "admin" },
+           { role: "readAnyDatabase", db: "admin" },
+           "readWrite"
+         ],
+       writeConcern: { w: "majority" , wtimeout: 5000 }
+     }
+   )
diff --git a/source/reference/method/db.removeUser.txt b/source/reference/method/db.removeUser.txt
@@ -4,13 +4,11 @@ db.removeUser()
 
 .. default-domain:: mongodb
 
-Definition
-----------
+.. deprecated:: 2.5.3
 
-.. method:: db.removeUser(username)
+   MongoDB 2.5.3 introduced a new model for user management and a new method
+   for removing a user, the :method:`db.dropUser()` method. Please see
+   :doc:`/reference/method/db.dropUser`.
 
-   Removes the specified username from the database.
-
-   The :method:`db.removeUser()` method has the following parameter:
-
-   .. include:: /reference/method/db.removeUser-param.rst
+For information on the deprecated ``db.removeUser()`` method, see
+:v2.4:`db.removeUser() </reference/method/db.removeUser>`.