DOCS-711 specified corrections

Author: Sam Kleinman

source/includes/warning-blocking-database.rst

@@ -7,7 +7,10 @@ clean (internal)
 .. dbcommand:: clean
 
    :dbcommand:`clean` is an internal command.
-   
-   .. include:: /includes/warning-blocking-database.rst
+
+   .. warning::
+
+      This command obtains a write lock on the affected database and will
+      block other operations until it has completed.
 
    .. write-lock, slave-ok

source/reference/command/clean.txt

@@ -34,6 +34,10 @@
 
    See :dbcommand:`copydb`  for similar functionality.
 
-   .. include:: /includes/warning-blocking-database.rst
+   .. warning::
+
+      This command obtains an intermittent write-lock on the
+      destination server, that can block other operations until it
+      completes.
 
 .. intermittent write-lock on destination server.

source/reference/command/clone.txt

@@ -31,19 +31,23 @@ collMod
       collection. By setting :collflag:`usePowerOf2Sizes`, you ensure
       that MongoDB will allocate space for documents in sizes that
       are powers of 2 (e.g. 4, 8, 16, 32, 64, 128, 256, 512...8388608).
-      With this option MongoDB will be able to more effectively reuse 
-      space. 
-      
+      With this option MongoDB will be able to more effectively reuse
+      space.
+
       :collflag:`usePowerOf2Sizes` is useful for collections where you
       will be inserting and deleting large numbers of documents to
       ensure that MongoDB will effectively use space on disk.
-      
-      .. note:: 
-         
-         In |release|, the :collflag:`usePowerOf2Sizes` is
-         subject to a limitation where MongoDB ineffectively reuses
-         spaces larger than 8 megabytes. See, :issue:`SERVER-7238` for
-         more information.
-
-   .. include:: /includes/warning-blocking-database.rst
-   
+
+      .. note::
+         .. versionchanged:: 2.2.1
+            If you're using :collflag:`usePowerOf2Sizes`, ensure
+            you use at least 2.2.1 to avoid the issue described in
+            :issue:`SERVER-7238`.
+
+         :collflag:`usePowerOf2Sizes` only affects subsequent
+         allocations cased by document insertion or record relocation
+         as a result of document growth, and *does not* affect
+         existing allocations.
+
+         This command obtains a write lock on the affected database
+         and will block other operations until it has completed.

source/reference/command/collMod.txt

@@ -8,7 +8,11 @@ copydbgetnonce (internal)
 
    Client libraries use :dbcommand:`copydbgetnonce` to get a one-time
    password for use with the :dbcommand:`copydb` command.
-   
-   .. include:: /includes/warning-blocking-database.rst
+
+   .. note::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed; however, the
+      write lock for this operation is short lived.
 
    .. write-lock, admin-only

source/reference/command/copydbgetnonce.txt

@@ -42,4 +42,9 @@ create
    The :method:`db.createCollection()` provides a wrapper function that
    provides access to this functionality.
 
-   .. include:: /includes/warning-blocking-database.rst
+   .. note::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed. The write
+      lock for this operation is typically short lived; however,
+      allocations for large capped collections may take longer.

source/reference/command/create.txt

@@ -7,7 +7,10 @@ diagLogging (internal)
 .. dbcommand:: diagLogging
 
    :dbcommand:`diagLogging` is an internal command.
-   
-   .. include:: /includes/warning-blocking-database.rst
+
+   .. warning::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed.
 
    .. write-lock, slave-ok,

source/reference/command/diagLogging.txt

@@ -23,4 +23,7 @@ drop
    Note that this command also removes any indexes associated with the
    dropped collection.
 
-   .. include:: /includes/warning-blocking-database.rst
+   .. warning::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed.

source/reference/command/drop.txt

@@ -6,7 +6,7 @@ dropIndexes
 
 .. dbcommand:: dropIndexes
 
-   The :dbcommand:`dropIndexes` command drops one or all indexes from 
+   The :dbcommand:`dropIndexes` command drops one or all indexes from
    the current collection.
    To drop all indexes, issue the command like so:
 
@@ -28,4 +28,7 @@ dropIndexes
 
       db.collection.dropIndex("age_1");
 
-   .. include:: /includes/warning-blocking-database.rst
+   .. warning::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed.

source/reference/command/dropIndexes.txt

@@ -16,4 +16,7 @@ emptycapped
    This command removes all records from the capped collection named
    ``events``.
 
-   .. include:: /includes/warning-blocking-database.rst
+   .. warning::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed.

source/reference/command/emptyCapped.txt

@@ -10,7 +10,7 @@ findAndModify
    returns a single document. By default, the returned document does
    not include the modifications made on the update. To return the
    document with the modifications made on the update, use the ``new``
-   option. 
+   option.
 
    The command has the following syntax:
 
@@ -22,42 +22,42 @@ findAndModify
    sub-document ``options``:
 
    :field document query:
-   
+
           Optional. Specifies the selection criteria for the
           modification. The ``query`` field employs the same
           :ref:`query selectors <query-selectors>` as used in the
           :method:`db.collection.find()` method. Although the query may
           match multiple documents, :dbcommand:`findAndModify` will
           only select one document to modify.
-          
+
           The ``query`` field has the following syntax:
-          
+
           .. code-block:: javascript
-          
+
              query: { <query expression> }
-          
-   :field document sort: 
+
+   :field document sort:
 
           Optional. Determines which document the operation will
           modify if the query selects multiple
           documents. :dbcommand:`findAndModify` will modify the first
           document in the sort order specified by this argument.
 
           The ``sort`` field has the following syntax:
-          
+
           .. code-block:: javascript
-          
+
              sort: { field1: value1, field2: value2, ... }
 
    :field boolean remove:
 
           Optional if ``update`` field exists. When ``true``, removes
           the selected document. The default is ``false``.
-          
+
           The ``remove`` field has the following syntax:
-          
+
           .. code-block:: javascript
-          
+
              remove: <boolean>
 
    :field document update:
@@ -82,16 +82,16 @@ findAndModify
 
              new: <boolean>
 
-   :field document fields: 
-   
+   :field document fields:
+
           Optional. A subset of fields to return.
-          
+
           .. code-block:: javascript
 
              fields: { field1: <boolean>, field2: <boolean> ... }
 
-   :field boolean upsert: 
-   
+   :field boolean upsert:
+
           Optional. Used in conjunction with the ``update`` field. When
           ``true``, the :dbcommand:`findAndModify` command creates a
           new document if the ``query`` returns no documents. The
@@ -119,17 +119,17 @@ findAndModify
       }
 
    This command performs the following actions:
-   
+
    #. The ``query`` finds a document in the ``people`` collection where the
       ``name`` field has the value ``Tom``, the ``state`` field has the
       value ``active`` and the ``rating`` field has a value
       :operator:`greater than <$gt>` 10.
-   
+
    #. The ``sort`` orders the results of the query in ascending order.
-   
+
    #. The update :operator:`increments <$inc>` the value of the
       ``score`` field by 1.
-   
+
    #. The command returns the original unmodified document
       selected for this update.
 
@@ -154,4 +154,9 @@ findAndModify
       :program:`mongos` instances for non-sharded collections function
       normally.
 
-   .. include:: /includes/warning-blocking-database.rst
+   .. note::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed; however,
+      typically the write lock is short lived and equivelent to other
+      similar :method:`update() <db.collection.update()>` operations.

source/reference/command/findAndModify.txt

@@ -7,7 +7,10 @@ godinsert (internal)
 .. dbcommand:: godinsert
 
    :dbcommand:`godinsert` is an internal command for testing purposes only.
-   
-   .. include:: /includes/warning-blocking-database.rst
+
+   .. note::
+
+      This command obtains a write lock on the affected database and will
+      block other operations until it has completed.
 
    .. write-lock, slave-ok

source/reference/command/godinsert.txt

@@ -51,6 +51,10 @@ profile
                 shell.
 
    .. include:: /includes/note-disable-profiling-fsynclock.rst
-   
-   .. include:: /includes/warning-blocking-database.rst
 
+   .. note::
+
+      This command obtains a write lock on the affected database and will
+      block other operations until it has completed; however the write
+      lock is only in place while the enabling and disabling the
+      profiler, which is typically a short operation.

source/reference/command/profile.txt

@@ -27,4 +27,7 @@ reIndex
 
       db.collection.reIndex();
 
-   .. include:: /includes/warning-blocking-database.rst
+   .. warning::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed.

source/reference/command/reIndex.txt

@@ -9,6 +9,9 @@ recvChunkStart (internal)
    :dbcommand:`_recvChunkStart` is an internal command. Do not call
    directly.
 
-   .. include:: /includes/warning-blocking-database.rst
+   .. warning::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed.
 
    .. admin-only, write-lock

source/reference/command/recvChunkStart.txt

@@ -14,6 +14,10 @@ shardingState
 
       { shardingState: 1 }
 
-   .. include:: /includes/warning-blocking-database.rst
+   .. warning::
+
+      This command obtains a write lock on the affected database and
+      will block other operations until it has completed; however, the
+      operation is typically short lived.
 
    .. admin-only