DOCSP-45429: sort for update and replace one (mongodb#581)

* DOCSP-45429: sort for update and replace one

* FP tech review 1

Author: rustagir

source/fundamentals/crud/write-operations/replace.txt

@@ -183,6 +183,23 @@ The ``ReplaceOptions`` class contains the following properties:
 
        **Data Type:** ``bool``
 
+   * - ``Sort``
+     - Determines which document the operation replaces if the query
+       selects multiple documents, because the replace operation replaces
+       the first document in the sort order specified. To set this
+       option, you must instantiate an ``ReplaceOptions<T>`` instance
+       that uses a generic type that models your data, as shown in the
+       following code:
+
+       .. code-block:: csharp
+
+          var options = new ReplaceOptions<Restaurant>
+          {
+            Sort = Builders<Restaurant>.Sort.Ascending(r => r.Name)
+          };
+
+       **Data Type:** ``SortDefinition<T>``
+
    * - ``Let``
      - Gets or sets the let document. 
        See :manual:`the {+mdb-server+} manual </reference/command/update/#std-label-update-let-syntax>`
@@ -268,4 +285,5 @@ see the following API documentation:
 * `ReplaceOne() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.ReplaceOne.html>`__
 * `ReplaceOneAsync() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.ReplaceOneAsync.html>`__
 * `ReplaceOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReplaceOptions.html>`__
-* `ReplaceOneResult <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReplaceOneResult.html>`__
+* `ReplaceOneResult
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReplaceOneResult.html>`__

source/includes/page-templates/update/update.rst

@@ -192,6 +192,23 @@ The ``UpdateOptions`` class contains the following properties:
 
        **Data Type:** ``bool``
 
+   * - ``Sort``
+     - Determines which document the operation updates if the query
+       selects multiple documents, because the update operation updates
+       the first document in the sort order specified. To set this
+       option, you must instantiate an ``UpdateOptions<T>`` instance
+       that uses a generic type that models your data, as shown in the
+       following code:
+
+       .. code-block:: csharp
+
+          var options = new UpdateOptions<Restaurant>
+          {
+            Sort = Builders<Restaurant>.Sort.Ascending(r => r.Name)
+          };
+
+       **Data Type:** ``SortDefinition<T>``
+
    * - ``Let``
      - Gets or sets the let document. 
        See :manual:`the {+mdb-server+} manual </reference/command/update/#std-label-update-let-syntax>`

source/whats-new.txt

@@ -167,9 +167,11 @@ The 3.1 driver release includes the following new features:
   Vector Search, see :atlas:`Run Vector Search Queries </atlas-vector-search/vector-search-stage>`
   in the Atlas Search documentation.
 
-- Adds support for the ``sort`` option to be passed to update commands. To learn more about
-  using update commands with the {+driver-short+}, see :ref:`csharp-update-one` and
-  :ref:`csharp-update-many`.
+- Adds a sort option for update and replace operations. This change
+  allows you to set a sort order if multiple documents match your
+  filter when attempting to update or replace a single document. To
+  learn more, see the :ref:`csharp-update-one` and
+  :ref:`csharp-replace-operation` guides.
 
 For more information about this release, see the :github:`v3.1 release notes
 </mongodb/mongo-csharp-driver/releases/tag/v3.1.0>`.