DOCS-5194: showDiskLoc() is replaced with showRecordId()

config/redirects.yaml

@@ -431,6 +431,13 @@ code: 301
 outputs:
   - 'before-v2.6'
 ---
+from: '/reference/method/cursor.showDiskLoc'
+to: '/reference/method/cursor.showRecordId'
+type: 'redirect'
+code: 301
+outputs:
+  - 'after-v3.0'
+---
 from: '/reference/method/setVerboseShell'
 to: '/reference/method'
 type: 'redirect'
@@ -902,4 +909,4 @@ code: 303
 outputs:
  - 'before-v3.0'
  - 'manual'
-...
+...

source/includes/example-showRecordId.rst

@@ -0,0 +1,46 @@
+The following operation appends the :method:`~cursor.showRecordId()`
+method to the :method:`db.collection.find()` method in order to include
+storage engine record information in the matching documents:
+
+.. code-block:: javascript
+
+   db.collection.find( { a: 1 } ).showRecordId()
+
+The operation returns the following documents, which include the ``$recordId``
+field:
+
+.. code-block:: javascript
+
+   {
+     "_id" : ObjectId("53908ccb18facd50a75bfbac"),
+     "a" : 1,
+     "b" : 1,
+     "$recordId" : NumberLong(168112)
+   }
+   {
+      "_id" : ObjectId("53908cd518facd50a75bfbad"),
+      "a" : 1,
+      "b" : 2,
+      "$recordId" : NumberLong(168176)
+   }
+
+You can :term:`project <projection>` the added field ``$recordId``, as in the
+following example:
+
+.. code-block:: javascript
+
+   db.collection.find( { a: 1 }, { $recordId: 1 } ).showRecordId()
+
+This query returns only the ``_id`` field and the ``$recordId``
+field in the matching documents:
+
+.. code-block:: javascript
+
+   {
+     "_id" : ObjectId("53908ccb18facd50a75bfbac"),
+     "$recordId" : NumberLong(168112)
+   }
+   {
+      "_id" : ObjectId("53908cd518facd50a75bfbad"),
+      "$recordId" : NumberLong(168176)
+   }

source/includes/ref-toc-method-cursor.yaml

@@ -66,9 +66,9 @@ name: ":method:`cursor.readPref()`"
 file: /reference/method/cursor.readPref
 description: "Specifies a :term:`read preference` to a cursor to control how the client directs queries to a :term:`replica set`."
 ---
-name: ":method:`cursor.showDiskLoc()`"
-file: /reference/method/cursor.showDiskLoc
-description: "Returns a cursor with modified documents that include the on-disk location of the document."
+name: ":method:`cursor.showRecordId()`"
+file: /reference/method/cursor.showRecordId
+description: "Adds an internal storage engine ID field to each document returned by the cursor."
 ---
 name: ":method:`cursor.size()`"
 file: /reference/method/cursor.size

source/reference/method/cursor.showRecordId.txt

@@ -0,0 +1,26 @@
+=====================
+cursor.showRecordId()
+=====================
+
+.. default-domain:: mongodb
+
+.. method:: cursor.showRecordId()
+
+   .. versionchanged:: 3.2
+      This method replaces the previous ``cursor.showDiskLoc()``.
+
+   Modifies the output of a query by adding a field ``$recordId`` to
+   matching documents. ``$recordId`` is the internal key which uniquely
+   identifies a document in a collection. It has the form:
+
+   .. code-block:: javascript
+
+      "$recordId": NumberLong(<int>)
+
+   :returns: A modified cursor object that contains documents with
+             appended information describing the internal record key.
+
+Example
+-------
+
+.. include:: /includes/example-showRecordId.rst

source/reference/operator/meta/showDiskLoc.txt

@@ -6,33 +6,6 @@ $showDiskLoc
 
 .. operator:: $showDiskLoc
 
-   :operator:`$showDiskLoc` option adds a field ``$diskLoc`` to the
-   returned documents. The value of the added ``$diskLoc`` field is a
-   document that contains the disk location information:
-
-   .. code-block:: javascript
-
-      "$diskLoc": {
-        "file": <int>,
-        "offset": <int>
-      }
-
-   The :program:`mongo` shell provides the
-   :method:`cursor.showDiskLoc()` method for :operator:`$showDiskLoc`:
-
-   .. code-block:: javascript
-
-      db.collection.find().showDiskLoc()
-
-   You can also specify the :operator:`$showDiskLoc` option in either
-   of the following forms:
-
-   .. code-block:: javascript
-
-      db.collection.find( { <query> } )._addSpecial("$showDiskLoc" , true)
-      db.collection.find( { $query: { <query> }, $showDiskLoc: true } )
-
-Example
--------
-
-.. include:: /includes/example-showDiskLoc.rst
+   .. deprecated:: 3.2
+      The :operator:`$showDiskLoc` operator is deprecated. Instead use the
+      :method:`cursor.showRecordId()` method.

source/release-notes/3.2-compatibility.txt

@@ -80,7 +80,7 @@ can drop and recreate the index:
       use test
       db.legacyOrders.dropIndex( "x_1" )
 
-   or by key: 
+   or by key:
 
    .. code-block:: javascript
 
@@ -149,6 +149,11 @@ Driver Compatibility Changes
 A driver upgrade is necessary to support :dbcommand:`find` and
 :dbcommand:`getMore`.
 
+General Compatibility Changes
+-----------------------------
+
+In MongoDB 3.2, ``cursor.showDiskLoc()`` is deprecated in favor of
+:method:`cursor.showRecordId()`, and both return a new document format.
 
 Additional Information
 ----------------------