DOCSP-24028 objectid in mongosh (#2731)

* DOCSP-28696 ObjectId in mongosh server updates

* DOCSP-28696 ObjectId in mongosh server updates

* DOCSP-28696 ObjectId in mongosh server updates

* DOCSP-28696 ObjectId in mongosh server updates

* DOCSP-28696 ObjectId in mongosh server updates

* DOCSP-28696 ObjectId in mongosh server updates

* DOCSP-28696 mongosh updates for server ticket

* Review feedback

* Staging fixes

* Staging fixes

Author: Dave Cuthbert

source/includes/fact-ObjectId-construct.rst

@@ -6,9 +6,9 @@
 
 - A 3-byte incrementing counter, initialized to a random value.
 
-While the BSON format itself is little-endian, the timestamp and
-counter values are big-endian, the most significant bytes appear first
-in the byte sequence.
+For timestamp and counter values, the most significant bytes appear
+first in the byte sequence (big-endian). This is unlike other BSON
+values, where the least significant bytes appear first (little-endian).
 
 If an integer value is used to create an ObjectId, the integer replaces
 the timestamp.

source/includes/reference/fact-objectid-and-mongosh.rst

@@ -0,0 +1,5 @@
+Starting in MongoDB 5.0, :binary:`mongosh` replaces the legacy ``mongo``
+shell. The ``ObjectId()`` methods work differently in ``mongosh`` than
+in the legacy ``mongo`` shell. For more information on the legacy
+methods, see :ref:`Legacy mongo Shell <mongo>`.
+

source/reference/bson-types.txt

@@ -112,9 +112,11 @@ benefits:
 
      .. include:: /includes/fact-ObjectId-timestamp-order.rst
 
-.. seealso::
+Use the :method:`ObjectId()` methods to set and retrieve ObjectId
+values.
+
+.. include:: /includes/reference/fact-objectid-and-mongosh.rst
 
-   :method:`ObjectId()`
 
 .. _document-bson-type-string:
 

source/reference/method/ObjectId.txt

@@ -1,3 +1,5 @@
+.. _server-objectid:
+
 ==========
 ObjectId()
 ==========
@@ -28,10 +30,10 @@ Description
    .. list-table::
       :header-rows: 1
       :widths: 20 80
-   
+
       * - Input Type
         - Description
-   
+
       * - ``hexadecimal``
         - Optional. A 24 character hexadecimal string value for the new
           ObjectId.
@@ -41,28 +43,31 @@ Description
           :wikipedia:`Unix epoch` to create the new timestamp. 
 
 
-Methods and Attributes
------------------------
+Methods
+-------
 
-:method:`ObjectId()` has the following attribute and methods:
+:method:`ObjectId()` has the following methods:
 
 .. list-table::
    :header-rows: 1
    :widths: 30 70
 
-   * - Attribute/Method
+   * - Methods
      - Description
-   
-   * - ``str``
-     - Returns the hexadecimal string representation of the object.
+
    * - :method:`ObjectId.getTimestamp()`
      - Returns the timestamp portion of the object as a Date.
+
    * - :method:`ObjectId.toString()`
-     - Returns the JavaScript representation in the form of a string
-       literal "``ObjectId(...)``".
+     - Returns the ObjectId as a hexadecimal string.
+
    * - :method:`ObjectId.valueOf()`
-     - Returns the representation of the object as a hexadecimal
-       string. The returned string is the ``str`` attribute.
+     - Returns ``ObjectId.self``.
+
+Behavior
+--------
+
+.. include:: /includes/reference/fact-objectid-and-mongosh.rst
 
 Examples
 --------
@@ -74,40 +79,25 @@ To generate a new ObjectId, use :method:`ObjectId()` with no argument:
 
 .. code-block:: javascript
 
-   x = ObjectId()
+   newObjectId = ObjectId()
 
-In this example, the value of ``x`` is:
+In this example, the value of ``newObjectId`` is:
 
 .. code-block:: javascript
 
    ObjectId("507f1f77bcf86cd799439011")
 
-Specify a Hexadecimal String
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To generate a new ObjectId using :method:`ObjectId()` with a unique
-hexadecimal string:
-
-.. code-block:: javascript
-
-   y = ObjectId("507f191e810c19729de860ea")
+Return a Hexadecimal String
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In this example, the value of ``y`` would be:
+To return the ObjectId as a hexadecimal string, use the ``toString()``
+method.
 
 .. code-block:: javascript
 
-   ObjectId("507f191e810c19729de860ea")
+   ObjectId("507f191e810c19729de860ea").toString()
 
-Access the Hexadecimal String
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Access the ``str`` attribute of an ``ObjectId()`` object, as follows:
-
-.. code-block:: javascript
-
-   ObjectId("507f191e810c19729de860ea").str
-
-This operation will return the following hexadecimal string:
+The method returns:
 
 .. code-block:: none
 
@@ -116,23 +106,39 @@ This operation will return the following hexadecimal string:
 Specify an Integer String
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Generate a new ObjectId using an integer.
+If you want to adjust the ObjectId timestamp, use an integer to generate
+a new ObjectId.
 
 .. code-block:: javascript
 
    newObjectId = ObjectId(32)
 
-The ObjectId resembles:
+The ObjectId value resembles:
 
 .. code-block:: javascript
 
    ObjectId("00000020f51bb4362eee2a4d")
 
-The first four bytes of the ObjectId are the number of seconds since
-the :wikipedia:`Unix epoch`. In this example ``32`` seconds,
-represented in hexadecimal as ``00000020``, are added. A five byte
-random element and a three byte counter make up the rest of the
-ObjectId.
+The example ObjectId consists of:
+
+- A four byte time stamp, ``00000020``
+- A five byte random element, ``f51bb4362e``
+- A three byte counter, ``ee2a4d``
+
+The first four bytes of the ObjectId are the number of seconds since the
+:wikipedia:`Unix epoch`. In this example, the ObjectId timestamp is
+``00000020`` which is ``32`` in hexadecimal.
+
+Specify a Hexadecimal String
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to use a hexadecimal string to specify an ObjectId, pass a
+unique, 24 character hexadecimal value when you call
+:method:`ObjectId()`:
+
+.. code-block:: javascript
+
+   newObjectId = ObjectId("507f191e810c19729de860ea")
 
 .. seealso::