DOCS-17365 ObjectId with integer arg (#776)

* DOCS-17365 ObjectId with integer arg

* Staging updates

* Review feedback

* Review feedback

* Staging updates

* Review feedback

* Review feedback

* review feedback

Author: Dave

source/includes/fact-ObjectId-construct.rst

@@ -1,11 +1,15 @@
-- a 4-byte *timestamp value*, representing the ObjectId's creation,
-  measured in seconds since the Unix epoch
+- A 4-byte timestamp, representing the ObjectId's creation, measured
+  in seconds since the Unix epoch.
 
-- a 5-byte *random value* generated once per process. This random value
+- A 5-byte random value generated once per process. This random value
   is unique to the machine and process.
 
-- a 3-byte *incrementing counter*, initialized to a random value
+- 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.
+
+If an integer value is used to create an ObjectId, the integer replaces
+the timestamp.
 
-While the BSON format itself is little-endian, the *timestamp* and
-*counter* values are big-endian, with the most significant bytes
-appearing first in the byte sequence.

source/reference/method/ObjectId.txt

@@ -15,34 +15,30 @@ ObjectId
 Description
 -----------
 
-.. method:: ObjectId(<hexadecimal>)
+.. method:: ObjectId(<value>)
 
-   Returns a new :ref:`objectid` value. The 12-byte :ref:`objectid`
-   value consists of:
+   Returns a new :ref:`objectid`. The 12-byte :ref:`objectid` consists
+   of:
 
    .. include:: /includes/fact-ObjectId-construct.rst
 
-   :method:`ObjectId()` can accept the following parameter:
+   :method:`ObjectId()` can accept one of the following inputs:
 
 
    .. list-table::
       :header-rows: 1
-      :widths: 20 20 80
-   
-      * - Field
-   
-        - Type
+      :widths: 20 80
 
+      * - Input Type
         - Description
 
       * - ``hexadecimal``
-   
-        - String
-   
-        - Optional. A 24 character hexadecimal string value for the new ObjectId.
-          
-          
-   
+        - Optional. A 24 character hexadecimal string value for the new
+          ObjectId.
+
+      * - ``integer``
+        - Optional. The integer value, in seconds, is added to the
+          :wikipedia:`Unix epoch` to create the new timestamp. 
 
 
 Methods and Attributes
@@ -58,20 +54,13 @@ Methods and Attributes
      - 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(...)``".
-
    * - :method:`ObjectId.valueOf()`
-
      - Returns the representation of the object as a hexadecimal
        string. The returned string is the ``str`` attribute.
 
@@ -87,7 +76,7 @@ To generate a new ObjectId, use :method:`ObjectId()` with no argument:
 
    x = ObjectId()
 
-In this example, the value of ``x`` would be:
+In this example, the value of ``x`` is:
 
 .. code-block:: javascript
 
@@ -124,6 +113,27 @@ This operation will return the following hexadecimal string:
 
    507f191e810c19729de860ea
 
+Specify an Integer String
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generate a new ObjectId using an integer.
+
+.. code-block:: javascript
+
+   newObjectId = ObjectId(32)
+
+The ObjectId 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.
+
 .. seealso::
 
    :ref:`ObjectId BSON Type <objectid>`