DOCS-15547 show record id (#1692) (#1703)

* DOCS-15547-show-record-id

* DOCS-15547-show-record-id

* DOCS-15547-show-record-id

* DOCS-15547-show-record-id

* DOCS-15547-show-record-id

* DOCS-15547-show-record-id

* DOCS-15547-show-record-id

* DOCS-15547-show-record-id

* DOCS-15547-show-record-id

Co-authored-by: jason-price-mongodb <[email protected]>

Co-authored-by: jason-price-mongodb <[email protected]>

Author: jason-price-mongodb

source/includes/example-showRecordId.rst

@@ -1,46 +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:
+The example uses this ``pizzas`` collection:
 
 .. code-block:: javascript
 
-   db.collection.find( { a: 1 } ).showRecordId()
+   db.pizzas.insertMany( [
+      { type: "pepperoni", size: "small", price: 4 },
+      { type: "cheese", size: "medium", price: 7 },
+      { type: "vegan", size: "large", price: 8 }
+   ] )
 
-The operation returns the following documents, which include the ``$recordId``
-field:
+The following :method:`~db.collection.find()` example uses
+:method:`~cursor.showRecordId()` to append the ``$recordId`` to the
+``pizza`` document fields in the output:
 
 .. 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:
+   db.pizzas.find().showRecordId()
 
-.. 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:
+Example output:
 
 .. code-block:: javascript
-
-   {
-     "_id" : ObjectId("53908ccb18facd50a75bfbac"),
-     "$recordId" : NumberLong(168112)
-   }
-   {
-      "_id" : ObjectId("53908cd518facd50a75bfbad"),
-      "$recordId" : NumberLong(168176)
-   }
+   :copyable: false
+
+   [
+      {
+         _id: ObjectId("62ffc70660b33b68e8f30435"),
+         type: 'pepperoni',
+         size: 'small',
+         price: 4,
+         '$recordId': Long("1")
+      },
+      {
+         _id: ObjectId("62ffc70660b33b68e8f30436"),
+         type: 'cheese',
+         size: 'medium',
+         price: 7,
+         '$recordId': Long("2")
+      },
+      {
+         _id: ObjectId("62ffc70660b33b68e8f30437"),
+         type: 'vegan',
+         size: 'large',
+         price: 8,
+         '$recordId': Long("3")
+      }
+   ]

source/reference/method/cursor.showRecordId.txt

@@ -10,25 +10,24 @@ cursor.showRecordId()
    :depth: 1
    :class: singlecol
 
-.. method:: cursor.showRecordId()
+Definition
+----------
 
+.. method:: cursor.showRecordId()
 
    .. include:: /includes/fact-mongo-shell-method.rst
 
-
-   .. 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:
+   Appends the ``$recordId`` field to documents returned by a query.
+   ``$recordId`` is the internal key that uniquely identifies a document
+   in a collection. ``$recordId`` format:
 
    .. code-block:: javascript
+      :copyable: false
 
-      "$recordId": NumberLong(<int>)
+      '$recordId': Long(<int>)
 
-   :returns: A modified cursor object that contains documents with
-             appended information describing the internal record key.
+   :returns: A modified cursor object that contains the document fields
+             and the appended ``$recordId`` field.
 
 Example
 -------