DOCS-356 repair revision

Author: Sam Kleinman

source/includes/note-repair.rst

@@ -0,0 +1,6 @@
+.. note::
+
+   When using :term:`journaling <journal>`, there is almost never
+   any need to run :dbcommand:`repairDatabase`. In the event of an
+   unclean shutdown, the server will be able restore the data files
+   to a pristine state automatically.

source/includes/warning-repair.rst

@@ -0,0 +1,8 @@
+.. warning::
+
+   In general, if you have an intact copy of your data, such as
+   would exist on a very recent backup or an intact member of a
+   :term:`replica set`, **do not** use :dbcommand:`repairDatabase`
+   or related options like :func:`db.repairDatabase()` in the
+   :program:`mongo` shell or :option:`mongod --repair`. Restore
+   from an intact copy of your data.

source/reference/commands.txt

@@ -1454,18 +1454,23 @@ Administration
 
 .. dbcommand:: repairDatabase
 
+   .. include:: /includes/warning-repair.rst
+
+   .. include:: /includes/note-repair.rst
+
    The :dbcommand:`repairDatabase` command checks and repairs errors and
    inconsistencies with the data storage. The command is analogous to
    a ``fsck`` command for file systems.
 
    If your :program:`mongod` instance is not running with journaling
-   and you experience an unexpected system restart or crash, you
+   the system experiences an unexpected system restart or crash, and
+   you have *no* other intact replica set members with this data, you
    should run the :dbcommand:`repairDatabase` command to ensure that
    there are no errors in the data storage.
 
    As a side effect, the :dbcommand:`repairDatabase` command will
-   compact the database, providing functionality equivalent to the
-   :dbcommand:`compact` command. Use the following syntax.
+   compact the database, as the :dbcommand:`compact` command. Use the
+   following syntax.
 
    .. code-block:: javascript
 
@@ -1485,6 +1490,9 @@ Administration
 
    - Use the shell to run the above command, as above.
 
+   - Use the :func:`db.repairDatabase()` in the :program:`mongo`
+     shell.
+
    - Run :program:`mongod` directly from your system's shell. Make sure
      that :program:`mongod` isn't already running, and that you issue
      this command as a user that has access to MongoDB's data
@@ -1499,23 +1507,12 @@ Administration
      .. note::
 
         This command will fail if your database is not a master or
-        primary. If you need to repair a secondary or slave node,
-        first restart the node as a standalone mongod by omitting the
-        :option:`--replSet <mongod --replSet>` or :option:`--slave
-        <mongod --slave>` options, as necessary.
-
-   - You may use the following shell helper:
-
-     .. code-block:: javascript
-
-        db.repairDatabase();
-
-   .. note::
-
-      When using :term:`journaling <journal>`, there is almost never any need to
-      run :dbcommand:`repairDatabase`. In the event of an unclean
-      shutdown, the server will be able restore the data files to a
-      pristine state automatically.
+        primary. In most cases, you should recover a currupt secondary
+        using the data from an existing intact node. If you need to
+        repair a secondary or slave node, first restart the node as a
+        standalone mongod by omitting the :option:`--replSet <mongod
+        --replSet>` or :option:`--slave <mongod --slave>` options, as
+        necessary.
 
 .. dbcommand:: shutdown
 

source/reference/javascript.txt

@@ -1014,26 +1014,18 @@ Database
 
    Removes the specified username from the database.
 
-.. function:: db.repairDatabase()
 
-   Checks and repairs errors and inconsistencies with the data
-   storage. This function is analogous to a ``fsck`` operation for
-   file systems. Additionally, the function compacts the database to
-   minimize the current database's storage utilization, similar to the
-   :dbcommand:`compact` command.
+.. function:: db.repairDatabase()
 
-   This function has the same effect as using the run-time option
-   ":option:`mongod --repair`," but only operates on the current
-   database.
+   .. include:: /includes/warning-repair.rst
 
-   This command provides a wrapper around the database command
-   ":dbcommand:`repairDatabase`".
-
-   .. warning::
+   .. include:: /includes/note-repair.rst
 
-      In general, if you have an intact :term:`replica set` member,
-      do not use :func:`db.repairDatabase()` and restore from the
-      other replica member.
+   :func:`db.repairDatabase()` provides a wrapper around the database
+   command :dbcommand:`repairDatabase`, and has the same effect as
+   the run-time option :option:`mongod --repair` option, limited to
+   *only* the current database. See :dbcommand:`repairDatabase` for
+   full documentation.
 
 .. function:: db.runCommand(command)
 

source/reference/mongod.txt

@@ -334,15 +334,12 @@ Options
 
 .. option:: --repair
 
-   Runs a repair routine on all databases.
+   Runs a repair routine on all databases. This is a similar operation
+   to the :dbcommand:`repairDatabase` database command.
 
-   .. note::
+   .. include:: /includes/warning-repair.rst
 
-      Because :program:`mongod` rewrites all of the database files
-      during the repair routine, if you do not run :option:`--repair`
-      under the same user account as :program:`mongod` usually runs,
-      you will need to run ``chown`` on your database files to correct
-      the permissions before starting :program:`mongod` again.
+   .. include:: /includes/note-repair.rst
 
    .. versionchanged:: 2.1.2
 
@@ -357,6 +354,7 @@ Options
    :program:`mongod` cleanly and restart with the :option:`--repair`
    option.
 
+
 .. option:: --repairpath <path>
 
    Specifies the root directory containing MongoDB data files, to use