DOCSP-48120: elemmatch method overload (#537)

* merge upstream

* small fix

* MW PR fixes 1

* RStam tech review

(cherry picked from commit ca969d4)

Author: rustagir

source/fundamentals/builders.txt

@@ -128,6 +128,25 @@ criteria. The following example returns documents that contain the value
    var builder = Builders<Flower>.Filter;
    var filter = builder.ElemMatch(f => f.Season, s => s == "Summer");
 
+.. tip:: ElemMatch() Overload
+
+   The ``ElemMatch()`` method has an overload that accepts a single *filter*
+   parameter. You can use this overload to perform ``$elemMatch``
+   queries directly against values. This functionality can support
+   queries that include nested ``$elemMatch`` statements.
+
+   The following code demonstrates how to construct a nested
+   ``$elemMatch`` query that uses multiple overloads of the
+   ``ElemMatch()`` method:
+
+   .. code-block:: csharp
+
+      // ElemMatch() with only filter parameter
+      var arrayFilter = Builders<MyEntry[]>.Filter.ElemMatch(<filter>);
+
+      // ElemMatch() with field name and filter parameters
+      var filter = Builders<MyClass>.Filter.ElemMatch(<array field name>, arrayFilter);
+
 To learn more about array operators, see the :manual:`Array Query Operators
 </reference/operator/query-array/>` guide in the {+mdb-server+} manual.
 
@@ -493,4 +512,5 @@ guide, see the following API Documentation:
 - `SortDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SortDefinitionBuilder-1.html>`__
 - `UpdateDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinitionBuilder-1.html>`__
 - `IndexKeysDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IndexKeysDefinitionBuilder-1.html>`__
-- `PipelineDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__
+- `PipelineDefinitionBuilder
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__

source/whats-new.txt

@@ -74,9 +74,10 @@ The 3.3 driver release includes the following new features:
 - Adds support for the ``$rankFusion`` aggregation stage, which enables rank-based
   result scoring on combined results from multiple pipelines.
 
-- Adds support for nested :manual:`$elemMatch </reference/operator/query/elemMatch/>`
-  queries by providing an overload of the ``ElemMatch()`` method that takes only a filter
-  parameter. To learn more, see the :ref:`csharp-builders-array-operators` section of the
+- Adds support for :manual:`$elemMatch </reference/operator/query/elemMatch/>`
+  queries directly against values by providing an overload of the
+  ``ElemMatch()`` method that takes only a filter parameter. To learn
+  more, see the :ref:`csharp-builders-array-operators` section of the
   Builders guide.
 
 - Adds support for using the ``OfType<T>()`` method and ``is`` operator to check
@@ -400,4 +401,4 @@ The 2.25 driver release includes the following new features:
 - Added support for overriding the ``"mongodb"`` service name with a custom one
   by using the ``srvServiceName`` connection option.
 - Improved behavior of bulk write operations to prevent enumerating the requests
-  parameter more than once.
+  parameter more than once.