DOCS-9766-v3.0: backport validate() changes for v3.0 and v3.2

source/reference/command/validate.txt

@@ -20,21 +20,23 @@ Definition
    indexes. The command returns information regarding the on-disk
    representation of the collection.
 
-   The ``validate`` command can be slow, particularly on larger data sets.
+   The ``validate`` command can be slow, particularly on larger data
+   sets. While the ``validate`` command is running, it holds an
+   exclusive lock on the collection.  This will block all reads and
+   writes until the validate command finishes.
 
-   The following example validates the contents of the collection named
-   ``users``.
+   :dbcommand:`validate` has the following prototype form:
 
    .. code-block:: javascript
 
-      { validate: "users" }
+      { validate: <collection> }
 
    You may also specify one of the following options:
 
    - ``full: true`` provides a more thorough scan of the data.
 
-   - ``scandata: false`` skips the scan of the base collection
-      without skipping the scan of the index.
+   - ``scandata: false`` skips the scan of the collection data
+     without skipping scans of any indexes.
 
    The :program:`mongo` shell also provides a wrapper
    :method:`db.collection.validate()`:
@@ -43,30 +45,74 @@ Definition
 
       db.collection.validate();
 
-   Use one of the following forms to perform the full collection
-   validation:
+Examples
+--------
 
-   .. code-block:: javascript
+Use one of the following forms to validate a collection:
 
-      db.collection.validate(true)
-      db.runCommand( { validate: "collection", full: true } )
+.. code-block:: javascript
 
-   .. warning:: This command is resource intensive and may have an
-      impact on the performance of your MongoDB instance.
+   db.collection.validate()
+   db.collection.validate(true)
+   db.runCommand( { validate: "collection", full: true } )
 
-   .. todo:: link to the document with these statistics
+.. note::
 
-   .. read-lock
+   Due to the manner in which :dbcommand:`validate` scans data
+   structures, even a full collection validation cannot detect all
+   forms of corruption on MMAPv1 storage engine data files.
 
 Output
 ------
 
+.. include:: /includes/note-output-may-vary.rst
+
+:dbcommand:`validate` produces different output depending on which
+:doc:`storage engine</core/storage-engines>` you are using. Specify
+``{ full: true }`` for more detailed output.
+
+The following fields are common to the
+:doc:`MMAPv1</core/mmapv1>` and :doc:`WiredTiger</core/wiredtiger>`
+storage engines:
+
 .. data:: validate.ns
 
    The full namespace name of the collection. Namespaces include the
    database name and the collection name in the form
    ``database.collection``.
 
+.. data:: validate.nrecords
+
+   The number of :term:`documents <document>` in the collection.
+
+.. data:: validate.nIndexes
+
+   The number of indexes on the collection.
+
+.. data:: validate.keysPerIndex
+
+   A document containing a field for each index. The value for each
+   field is the number of keys (or documents referenced) in the index.
+
+.. data:: validate.valid
+
+   A boolean that is ``true`` if :dbcommand:`validate` determines that
+   all aspects of the collection are valid. When ``false``, see the
+   :data:`~validate.errors` field for more information.
+
+.. data:: validate.errors
+
+   If the collection is not valid (i.e
+   :data:`~validate.valid` is false), this field will contain a message
+   describing the validation error.
+
+.. data:: validate.ok
+
+   An integer with the value ``1`` when the command succeeds. If the
+   command fails the :data:`~validate.ok` field has a value of ``0``.
+
+The following fields are specific to :doc:`MMAPv1</core/mmapv1>`:
+
 .. data:: validate.firstExtent
 
    The disk location of the first extent in the collection. The value
@@ -125,10 +171,6 @@ Output
    record headers, nor space in a file unallocated to any
    extent. :data:`~validate.datasize` includes record :term:`padding`.
 
-.. data:: validate.nrecords
-
-   The number of :term:`documents <document>` in the collection.
-
 .. data:: validate.lastExtentSize
 
    The size of the last new extent created in this collection. This
@@ -226,30 +268,3 @@ Output
 .. data:: validate.deletedSize
 
    The size of all deleted or "free" records in the collection.
-
-.. data:: validate.nIndexes
-
-   The number of indexes on the data in the collection.
-
-.. data:: validate.keysPerIndex
-
-   A document containing a field for each index, named after the
-   index's name, that contains the number of keys, or documents
-   referenced, included in the index.
-
-.. data:: validate.valid
-
-   Boolean. ``true``, unless :dbcommand:`validate` determines that an
-   aspect of the collection is not valid. When ``false``, see the
-   :data:`~validate.errors` field for more information.
-
-.. data:: validate.errors
-
-   Typically empty; however, if the collection is not valid (i.e
-   :data:`~validate.valid` is false), this field will contain a message
-   describing the validation error.
-
-.. data:: validate.ok
-
-   Set to ``1`` when the command succeeds. If the command fails
-   the :data:`~validate.ok` field has a value of ``0``.