From 9f2935031853d17e240214b3da76f453a89d420f Mon Sep 17 00:00:00 2001
From: adelinowona <adelinowona@gmail.com>
Date: Tue, 5 Aug 2025 11:59:03 -0400
Subject: [PATCH 1/9] CSHARP-5672: Support sorting by value in updateDefinition
 builders

---
 src/MongoDB.Driver/SortDefinitionBuilder.cs   | 40 +++++++++++++++++++
 src/MongoDB.Driver/UpdateDefinitionBuilder.cs |  8 +++-
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/src/MongoDB.Driver/SortDefinitionBuilder.cs b/src/MongoDB.Driver/SortDefinitionBuilder.cs
index bec17d70ef3..4f1b09097d8 100644
--- a/src/MongoDB.Driver/SortDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/SortDefinitionBuilder.cs
@@ -130,6 +130,15 @@ public static SortDefinition<TDocument> MetaTextScore<TDocument>(this SortDefini
     /// <typeparam name="TDocument">The type of the document.</typeparam>
     public sealed class SortDefinitionBuilder<TDocument>
     {
+        /// <summary>
+        /// Creates a value ascending sort.
+        /// </summary>
+        /// <returns>An ascending sort.</returns>
+        public SortDefinition<TDocument> Ascending()
+        {
+            return new NoFieldDirectionalSortDefinition<TDocument>(SortDirection.Ascending);
+        }
+
         /// <summary>
         /// Creates an ascending sort.
         /// </summary>
@@ -170,6 +179,15 @@ public SortDefinition<TDocument> Combine(IEnumerable<SortDefinition<TDocument>>
             return new CombinedSortDefinition<TDocument>(sorts);
         }
 
+        /// <summary>
+        /// Creates a value descending sort.
+        /// </summary>
+        /// <returns>A descending sort.</returns>
+        public SortDefinition<TDocument> Descending()
+        {
+            return new NoFieldDirectionalSortDefinition<TDocument>(SortDirection.Descending);
+        }
+
         /// <summary>
         /// Creates a descending sort.
         /// </summary>
@@ -288,4 +306,26 @@ public override BsonDocument Render(RenderArgs<TDocument> args)
             return new BsonDocument(renderedField.FieldName, value);
         }
     }
+
+    internal sealed class NoFieldDirectionalSortDefinition<TDocument> : SortDefinition<TDocument>
+    {
+        private readonly SortDirection _direction;
+
+        public NoFieldDirectionalSortDefinition(SortDirection direction)
+        {
+            _direction = direction;
+        }
+
+        public override BsonDocument Render(RenderArgs<TDocument> args)
+        {
+            BsonValue value = _direction switch
+            {
+                SortDirection.Ascending => 1,
+                SortDirection.Descending => -1,
+                _ => throw new InvalidOperationException("Unknown value for " + typeof(SortDirection) + ".")
+            };
+
+            return new BsonDocument("direction",  value);
+        }
+    }
 }
diff --git a/src/MongoDB.Driver/UpdateDefinitionBuilder.cs b/src/MongoDB.Driver/UpdateDefinitionBuilder.cs
index be95f9a306c..d0729001c10 100644
--- a/src/MongoDB.Driver/UpdateDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/UpdateDefinitionBuilder.cs
@@ -1685,7 +1685,13 @@ public override BsonValue Render(RenderArgs<TDocument> args)
 
             if (_sort != null)
             {
-                document["$push"][renderedField.FieldName]["$sort"] = _sort.Render(args.WithNewDocumentType((IBsonSerializer<TItem>)itemSerializer));
+                var newArgs = args.WithNewDocumentType((IBsonSerializer<TItem>)itemSerializer);
+
+                var renderedSort = _sort is NoFieldDirectionalSortDefinition<TItem>
+                    ? _sort.Render(newArgs)["direction"]
+                    : _sort.Render(newArgs);
+
+                document["$push"][renderedField.FieldName]["$sort"] = renderedSort;
             }
 
             return document;

From ea3784a0b6b78843cf29b55b68fcedb677401ad6 Mon Sep 17 00:00:00 2001
From: adelinowona <adelinowona@gmail.com>
Date: Thu, 7 Aug 2025 11:03:31 -0400
Subject: [PATCH 2/9] add simple tests

---
 src/MongoDB.Driver/SortDefinitionBuilder.cs   |  5 ++++
 .../SortDefinitionBuilderTests.cs             | 27 +++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/src/MongoDB.Driver/SortDefinitionBuilder.cs b/src/MongoDB.Driver/SortDefinitionBuilder.cs
index 4f1b09097d8..a0911e106b2 100644
--- a/src/MongoDB.Driver/SortDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/SortDefinitionBuilder.cs
@@ -250,6 +250,11 @@ internal sealed class CombinedSortDefinition<TDocument> : SortDefinition<TDocume
         public CombinedSortDefinition(IEnumerable<SortDefinition<TDocument>> sorts)
         {
             _sorts = Ensure.IsNotNull(sorts, nameof(sorts)).ToList();
+
+            if (_sorts.Any(sort => sort is NoFieldDirectionalSortDefinition<TDocument>))
+            {
+                throw new InvalidOperationException("Value-based sort cannot be combined with other sorts. When sorting by the entire element value, no other sorting criteria can be applied.");
+            }
         }
 
         public override BsonDocument Render(RenderArgs<TDocument> args)
diff --git a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
index 29b18bdb264..52e3cd319e8 100644
--- a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
+++ b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
@@ -13,6 +13,7 @@
 * limitations under the License.
 */
 
+using System;
 using FluentAssertions;
 using MongoDB.Bson;
 using MongoDB.Bson.Serialization;
@@ -31,6 +32,14 @@ public void Ascending()
             Assert(subject.Ascending("a"), "{a: 1}");
         }
 
+        [Fact]
+        public void Ascending_no_field()
+        {
+            var subject = CreateSubject<BsonDocument>();
+
+            Assert(subject.Ascending(), "{direction: 1}");
+        }
+
         [Fact]
         public void Ascending_Typed()
         {
@@ -76,6 +85,16 @@ public void Combine_with_repeated_fields_using_extension_methods()
             Assert(sort, "{b: -1, a: -1}");
         }
 
+        [Fact]
+        public void Combine_with_value_based_sort_and_additional_sort_should_throw()
+        {
+            var subject = CreateSubject<BsonDocument>();
+
+            var exception = Record.Exception(() => subject.Ascending().Descending("b"));
+
+            exception.Should().BeOfType<InvalidOperationException>();
+        }
+
         [Fact]
         public void Descending()
         {
@@ -84,6 +103,14 @@ public void Descending()
             Assert(subject.Descending("a"), "{a: -1}");
         }
 
+        [Fact]
+        public void Descending_no_field()
+        {
+            var subject = CreateSubject<BsonDocument>();
+
+            Assert(subject.Descending(), "{direction: -1}");
+        }
+
         [Fact]
         public void Descending_Typed()
         {

From 121021d299499e76bf2c228aeaddaade237b4903 Mon Sep 17 00:00:00 2001
From: adelinowona <adelinowona@gmail.com>
Date: Mon, 11 Aug 2025 17:46:34 -0400
Subject: [PATCH 3/9] address pr comments

---
 src/MongoDB.Driver/SortDefinition.cs          |  3 ++
 src/MongoDB.Driver/SortDefinitionBuilder.cs   | 41 ++++++-------------
 src/MongoDB.Driver/SortDirectionExtensions.cs | 33 +++++++++++++++
 src/MongoDB.Driver/UpdateDefinitionBuilder.cs |  8 +---
 .../SortDefinitionBuilderTests.cs             |  4 +-
 5 files changed, 51 insertions(+), 38 deletions(-)
 create mode 100644 src/MongoDB.Driver/SortDirectionExtensions.cs

diff --git a/src/MongoDB.Driver/SortDefinition.cs b/src/MongoDB.Driver/SortDefinition.cs
index b66bda799a9..a7d6a8bfaed 100644
--- a/src/MongoDB.Driver/SortDefinition.cs
+++ b/src/MongoDB.Driver/SortDefinition.cs
@@ -47,6 +47,9 @@ public abstract class SortDefinition<TDocument>
         /// <returns>A <see cref="BsonDocument"/>.</returns>
         public abstract BsonDocument Render(RenderArgs<TDocument> args);
 
+        // TODO: remove this and refactor Render to return a BsonValue in 4.0
+        internal virtual BsonValue RenderAsBsonValue(RenderArgs<TDocument> args) => Render(args);
+
         /// <summary>
         /// Performs an implicit conversion from <see cref="BsonDocument"/> to <see cref="SortDefinition{TDocument}"/>.
         /// </summary>
diff --git a/src/MongoDB.Driver/SortDefinitionBuilder.cs b/src/MongoDB.Driver/SortDefinitionBuilder.cs
index a0911e106b2..9f01bd3a25c 100644
--- a/src/MongoDB.Driver/SortDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/SortDefinitionBuilder.cs
@@ -133,10 +133,10 @@ public sealed class SortDefinitionBuilder<TDocument>
         /// <summary>
         /// Creates a value ascending sort.
         /// </summary>
-        /// <returns>An ascending sort.</returns>
+        /// <returns>A value ascending sort.</returns>
         public SortDefinition<TDocument> Ascending()
         {
-            return new NoFieldDirectionalSortDefinition<TDocument>(SortDirection.Ascending);
+            return new ValueDirectionalSortDefinition<TDocument>(SortDirection.Ascending);
         }
 
         /// <summary>
@@ -182,10 +182,10 @@ public SortDefinition<TDocument> Combine(IEnumerable<SortDefinition<TDocument>>
         /// <summary>
         /// Creates a value descending sort.
         /// </summary>
-        /// <returns>A descending sort.</returns>
+        /// <returns>A value descending sort.</returns>
         public SortDefinition<TDocument> Descending()
         {
-            return new NoFieldDirectionalSortDefinition<TDocument>(SortDirection.Descending);
+            return new ValueDirectionalSortDefinition<TDocument>(SortDirection.Descending);
         }
 
         /// <summary>
@@ -251,7 +251,7 @@ public CombinedSortDefinition(IEnumerable<SortDefinition<TDocument>> sorts)
         {
             _sorts = Ensure.IsNotNull(sorts, nameof(sorts)).ToList();
 
-            if (_sorts.Any(sort => sort is NoFieldDirectionalSortDefinition<TDocument>))
+            if (_sorts.Any(sort => sort is ValueDirectionalSortDefinition<TDocument>))
             {
                 throw new InvalidOperationException("Value-based sort cannot be combined with other sorts. When sorting by the entire element value, no other sorting criteria can be applied.");
             }
@@ -295,42 +295,25 @@ public override BsonDocument Render(RenderArgs<TDocument> args)
         {
             var renderedField = _field.Render(args);
 
-            BsonValue value;
-            switch (_direction)
-            {
-                case SortDirection.Ascending:
-                    value = 1;
-                    break;
-                case SortDirection.Descending:
-                    value = -1;
-                    break;
-                default:
-                    throw new InvalidOperationException("Unknown value for " + typeof(SortDirection) + ".");
-            }
-
-            return new BsonDocument(renderedField.FieldName, value);
+            return new BsonDocument(renderedField.FieldName, _direction.ToBsonValue());
         }
     }
 
-    internal sealed class NoFieldDirectionalSortDefinition<TDocument> : SortDefinition<TDocument>
+    internal sealed class ValueDirectionalSortDefinition<TDocument> : SortDefinition<TDocument>
     {
         private readonly SortDirection _direction;
 
-        public NoFieldDirectionalSortDefinition(SortDirection direction)
+        public ValueDirectionalSortDefinition(SortDirection direction)
         {
             _direction = direction;
         }
 
+        internal override BsonValue RenderAsBsonValue(RenderArgs<TDocument> args) => _direction.ToBsonValue();
+
         public override BsonDocument Render(RenderArgs<TDocument> args)
         {
-            BsonValue value = _direction switch
-            {
-                SortDirection.Ascending => 1,
-                SortDirection.Descending => -1,
-                _ => throw new InvalidOperationException("Unknown value for " + typeof(SortDirection) + ".")
-            };
-
-            return new BsonDocument("direction",  value);
+            throw new InvalidOperationException(
+                "Value-based sort cannot be rendered as a document. You might be trying to use a value-based sort where a field-based sort is expected.");
         }
     }
 }
diff --git a/src/MongoDB.Driver/SortDirectionExtensions.cs b/src/MongoDB.Driver/SortDirectionExtensions.cs
new file mode 100644
index 00000000000..d71676e8239
--- /dev/null
+++ b/src/MongoDB.Driver/SortDirectionExtensions.cs
@@ -0,0 +1,33 @@
+/* Copyright 2010-present MongoDB Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+using System;
+using MongoDB.Bson;
+
+namespace MongoDB.Driver
+{
+    internal static class SortDirectionExtensions
+    {
+        internal static BsonValue ToBsonValue(this SortDirection direction)
+        {
+            return direction switch
+            {
+                SortDirection.Ascending => 1,
+                SortDirection.Descending => -1,
+                _ => throw new InvalidOperationException($"Invalid sort direction: {direction}.")
+            };
+        }
+    }
+}
\ No newline at end of file
diff --git a/src/MongoDB.Driver/UpdateDefinitionBuilder.cs b/src/MongoDB.Driver/UpdateDefinitionBuilder.cs
index d0729001c10..9f2bac9d8ff 100644
--- a/src/MongoDB.Driver/UpdateDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/UpdateDefinitionBuilder.cs
@@ -1685,13 +1685,7 @@ public override BsonValue Render(RenderArgs<TDocument> args)
 
             if (_sort != null)
             {
-                var newArgs = args.WithNewDocumentType((IBsonSerializer<TItem>)itemSerializer);
-
-                var renderedSort = _sort is NoFieldDirectionalSortDefinition<TItem>
-                    ? _sort.Render(newArgs)["direction"]
-                    : _sort.Render(newArgs);
-
-                document["$push"][renderedField.FieldName]["$sort"] = renderedSort;
+                document["$push"][renderedField.FieldName]["$sort"] = _sort.RenderAsBsonValue(args.WithNewDocumentType((IBsonSerializer<TItem>)itemSerializer));
             }
 
             return document;
diff --git a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
index 52e3cd319e8..0dbadc9f7a6 100644
--- a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
+++ b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
@@ -33,7 +33,7 @@ public void Ascending()
         }
 
         [Fact]
-        public void Ascending_no_field()
+        public void Ascending_value()
         {
             var subject = CreateSubject<BsonDocument>();
 
@@ -104,7 +104,7 @@ public void Descending()
         }
 
         [Fact]
-        public void Descending_no_field()
+        public void Descending_value()
         {
             var subject = CreateSubject<BsonDocument>();
 

From c0d08cf7f4e08ba03870ab603303bf943bbd68b3 Mon Sep 17 00:00:00 2001
From: adelinowona <adelinowona@gmail.com>
Date: Tue, 12 Aug 2025 20:42:52 -0400
Subject: [PATCH 4/9] address more pr comments

---
 src/MongoDB.Driver/IndexKeysDefinitionBuilder.cs | 15 +--------------
 src/MongoDB.Driver/SortDefinitionBuilder.cs      |  4 ++--
 src/MongoDB.Driver/SortDirectionExtensions.cs    |  2 +-
 3 files changed, 4 insertions(+), 17 deletions(-)

diff --git a/src/MongoDB.Driver/IndexKeysDefinitionBuilder.cs b/src/MongoDB.Driver/IndexKeysDefinitionBuilder.cs
index 6e500f4c9c2..1b42c938411 100644
--- a/src/MongoDB.Driver/IndexKeysDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/IndexKeysDefinitionBuilder.cs
@@ -487,20 +487,7 @@ public override BsonDocument Render(RenderArgs<TDocument> args)
         {
             var renderedField = _field.Render(args);
 
-            BsonValue value;
-            switch (_direction)
-            {
-                case SortDirection.Ascending:
-                    value = 1;
-                    break;
-                case SortDirection.Descending:
-                    value = -1;
-                    break;
-                default:
-                    throw new InvalidOperationException("Unknown value for " + typeof(SortDirection) + ".");
-            }
-
-            return new BsonDocument(renderedField.FieldName, value);
+            return new BsonDocument(renderedField.FieldName, _direction.Render());
         }
     }
 
diff --git a/src/MongoDB.Driver/SortDefinitionBuilder.cs b/src/MongoDB.Driver/SortDefinitionBuilder.cs
index 9f01bd3a25c..23e5f550f3e 100644
--- a/src/MongoDB.Driver/SortDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/SortDefinitionBuilder.cs
@@ -295,7 +295,7 @@ public override BsonDocument Render(RenderArgs<TDocument> args)
         {
             var renderedField = _field.Render(args);
 
-            return new BsonDocument(renderedField.FieldName, _direction.ToBsonValue());
+            return new BsonDocument(renderedField.FieldName, _direction.Render());
         }
     }
 
@@ -308,7 +308,7 @@ public ValueDirectionalSortDefinition(SortDirection direction)
             _direction = direction;
         }
 
-        internal override BsonValue RenderAsBsonValue(RenderArgs<TDocument> args) => _direction.ToBsonValue();
+        internal override BsonValue RenderAsBsonValue(RenderArgs<TDocument> args) => _direction.Render();
 
         public override BsonDocument Render(RenderArgs<TDocument> args)
         {
diff --git a/src/MongoDB.Driver/SortDirectionExtensions.cs b/src/MongoDB.Driver/SortDirectionExtensions.cs
index d71676e8239..7c930510974 100644
--- a/src/MongoDB.Driver/SortDirectionExtensions.cs
+++ b/src/MongoDB.Driver/SortDirectionExtensions.cs
@@ -20,7 +20,7 @@ namespace MongoDB.Driver
 {
     internal static class SortDirectionExtensions
     {
-        internal static BsonValue ToBsonValue(this SortDirection direction)
+        internal static BsonValue Render(this SortDirection direction)
         {
             return direction switch
             {

From 533fe3ec9d0bad1173d6a5bdd14988d9ef82105e Mon Sep 17 00:00:00 2001
From: adelinowona <adelinowona@gmail.com>
Date: Thu, 14 Aug 2025 03:21:53 -0400
Subject: [PATCH 5/9] fix tests

---
 src/MongoDB.Driver/SortDirectionExtensions.cs    |  6 ++----
 .../SortDefinitionBuilderTests.cs                | 16 +++++++++++++---
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/src/MongoDB.Driver/SortDirectionExtensions.cs b/src/MongoDB.Driver/SortDirectionExtensions.cs
index 7c930510974..c6b43d4ddc0 100644
--- a/src/MongoDB.Driver/SortDirectionExtensions.cs
+++ b/src/MongoDB.Driver/SortDirectionExtensions.cs
@@ -20,14 +20,12 @@ namespace MongoDB.Driver
 {
     internal static class SortDirectionExtensions
     {
-        internal static BsonValue Render(this SortDirection direction)
-        {
-            return direction switch
+        internal static BsonValue Render(this SortDirection direction) =>
+            direction switch
             {
                 SortDirection.Ascending => 1,
                 SortDirection.Descending => -1,
                 _ => throw new InvalidOperationException($"Invalid sort direction: {direction}.")
             };
-        }
     }
 }
\ No newline at end of file
diff --git a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
index 0dbadc9f7a6..9f4e4620d6a 100644
--- a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
+++ b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
@@ -37,7 +37,7 @@ public void Ascending_value()
         {
             var subject = CreateSubject<BsonDocument>();
 
-            Assert(subject.Ascending(), "{direction: 1}");
+            Assert(subject.Ascending(), "1");
         }
 
         [Fact]
@@ -108,7 +108,7 @@ public void Descending_value()
         {
             var subject = CreateSubject<BsonDocument>();
 
-            Assert(subject.Descending(), "{direction: -1}");
+            Assert(subject.Descending(), "-1");
         }
 
         [Fact]
@@ -144,10 +144,20 @@ public void MetaTextScore()
             Assert(subject.MetaTextScore("awesome"), "{awesome: {$meta: 'textScore'}}");
         }
 
+        [Fact]
+        public void CallingRenderOnValueBasedSortShouldThrow()
+        {
+            var subject = CreateSubject<BsonDocument>();
+
+            var exception = Record.Exception(() => subject.Ascending().Render(new RenderArgs<BsonDocument>()));
+
+            exception.Should().BeOfType<InvalidOperationException>();
+        }
+
         private void Assert<TDocument>(SortDefinition<TDocument> sort, string expectedJson)
         {
             var documentSerializer = BsonSerializer.SerializerRegistry.GetSerializer<TDocument>();
-            var renderedSort = sort.Render(new(documentSerializer, BsonSerializer.SerializerRegistry));
+            var renderedSort = sort.RenderAsBsonValue(new(documentSerializer, BsonSerializer.SerializerRegistry));
 
             renderedSort.Should().Be(expectedJson);
         }

From e998575b726f18dbf0f093edf906068c54a54d32 Mon Sep 17 00:00:00 2001
From: adelinowona <adelinowona@gmail.com>
Date: Thu, 14 Aug 2025 14:50:57 -0400
Subject: [PATCH 6/9] move overriden method

---
 src/MongoDB.Driver/SortDefinitionBuilder.cs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/MongoDB.Driver/SortDefinitionBuilder.cs b/src/MongoDB.Driver/SortDefinitionBuilder.cs
index 23e5f550f3e..4869e9c2a24 100644
--- a/src/MongoDB.Driver/SortDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/SortDefinitionBuilder.cs
@@ -308,12 +308,12 @@ public ValueDirectionalSortDefinition(SortDirection direction)
             _direction = direction;
         }
 
-        internal override BsonValue RenderAsBsonValue(RenderArgs<TDocument> args) => _direction.Render();
-
         public override BsonDocument Render(RenderArgs<TDocument> args)
         {
             throw new InvalidOperationException(
                 "Value-based sort cannot be rendered as a document. You might be trying to use a value-based sort where a field-based sort is expected.");
         }
+
+        internal override BsonValue RenderAsBsonValue(RenderArgs<TDocument> args) => _direction.Render();
     }
 }

From 8d9710ebe12fb7b466e6766ccc20d15b34f038ae Mon Sep 17 00:00:00 2001
From: adelinowona <adelinowona@gmail.com>
Date: Mon, 18 Aug 2025 23:53:43 -0400
Subject: [PATCH 7/9] fix test name and improve xml docs

---
 src/MongoDB.Driver/SortDefinitionBuilder.cs   | 20 +++++++++++++------
 .../SortDefinitionBuilderTests.cs             |  2 +-
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/src/MongoDB.Driver/SortDefinitionBuilder.cs b/src/MongoDB.Driver/SortDefinitionBuilder.cs
index 4869e9c2a24..aa1ac09a162 100644
--- a/src/MongoDB.Driver/SortDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/SortDefinitionBuilder.cs
@@ -131,7 +131,9 @@ public static SortDefinition<TDocument> MetaTextScore<TDocument>(this SortDefini
     public sealed class SortDefinitionBuilder<TDocument>
     {
         /// <summary>
-        /// Creates a value ascending sort.
+        /// Creates a value ascending sort that sorts documents by their entire document value. For example, "$sort: 1"
+        /// This is typically used when documents are simple values (like strings, numbers, or dates)
+        /// rather than complex objects with multiple fields.
         /// </summary>
         /// <returns>A value ascending sort.</returns>
         public SortDefinition<TDocument> Ascending()
@@ -140,7 +142,8 @@ public SortDefinition<TDocument> Ascending()
         }
 
         /// <summary>
-        /// Creates an ascending sort.
+        /// Creates an ascending sort based on a specific field within the document. For example, "$sort: {field: 1}"
+        /// This is used when documents are complex objects, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>An ascending sort.</returns>
@@ -150,7 +153,8 @@ public SortDefinition<TDocument> Ascending(FieldDefinition<TDocument> field)
         }
 
         /// <summary>
-        /// Creates an ascending sort.
+        /// Creates an ascending sort based on a specific field within the document. For example, "$sort: {field: 1}"
+        /// This is used when documents are complex objects, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>An ascending sort.</returns>
@@ -180,7 +184,9 @@ public SortDefinition<TDocument> Combine(IEnumerable<SortDefinition<TDocument>>
         }
 
         /// <summary>
-        /// Creates a value descending sort.
+        /// Creates a value descending sort that sorts documents by their entire document value. For example, "$sort: -1"
+        /// This is typically used when documents are simple values (like strings, numbers, or dates)
+        /// rather than complex objects with multiple fields.
         /// </summary>
         /// <returns>A value descending sort.</returns>
         public SortDefinition<TDocument> Descending()
@@ -189,7 +195,8 @@ public SortDefinition<TDocument> Descending()
         }
 
         /// <summary>
-        /// Creates a descending sort.
+        /// Creates a descending sort based on a specific field within the document. For example, "$sort: {field: -1}"
+        /// This is used when documents are complex objects, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>A descending sort.</returns>
@@ -199,7 +206,8 @@ public SortDefinition<TDocument> Descending(FieldDefinition<TDocument> field)
         }
 
         /// <summary>
-        /// Creates a descending sort.
+        /// Creates a descending sort based on a specific field within the document. For example, "$sort: {field: -1}"
+        /// This is used when documents are complex objects, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>A descending sort.</returns>
diff --git a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
index 9f4e4620d6a..b42e398d49b 100644
--- a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
+++ b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
@@ -145,7 +145,7 @@ public void MetaTextScore()
         }
 
         [Fact]
-        public void CallingRenderOnValueBasedSortShouldThrow()
+        public void Calling_render_on_value_based_sort_should_throw()
         {
             var subject = CreateSubject<BsonDocument>();
 

From 67ef77ee0c7ffd1aee31208e13a3f0d1fbea71d4 Mon Sep 17 00:00:00 2001
From: adelinowona <adelinowona@gmail.com>
Date: Tue, 19 Aug 2025 17:52:33 -0400
Subject: [PATCH 8/9] move test to be in order

---
 .../SortDefinitionBuilderTests.cs             | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
index b42e398d49b..a38f6d62207 100644
--- a/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
+++ b/tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs
@@ -49,6 +49,16 @@ public void Ascending_Typed()
             Assert(subject.Ascending("FirstName"), "{fn: 1}");
         }
 
+        [Fact]
+        public void Calling_render_on_value_based_sort_should_throw()
+        {
+            var subject = CreateSubject<BsonDocument>();
+
+            var exception = Record.Exception(() => subject.Ascending().Render(new RenderArgs<BsonDocument>()));
+
+            exception.Should().BeOfType<InvalidOperationException>();
+        }
+
         [Fact]
         public void Combine()
         {
@@ -144,16 +154,6 @@ public void MetaTextScore()
             Assert(subject.MetaTextScore("awesome"), "{awesome: {$meta: 'textScore'}}");
         }
 
-        [Fact]
-        public void Calling_render_on_value_based_sort_should_throw()
-        {
-            var subject = CreateSubject<BsonDocument>();
-
-            var exception = Record.Exception(() => subject.Ascending().Render(new RenderArgs<BsonDocument>()));
-
-            exception.Should().BeOfType<InvalidOperationException>();
-        }
-
         private void Assert<TDocument>(SortDefinition<TDocument> sort, string expectedJson)
         {
             var documentSerializer = BsonSerializer.SerializerRegistry.GetSerializer<TDocument>();

From f0ec8c051480743499ebf52d6f0d67db9e61bece Mon Sep 17 00:00:00 2001
From: adelinowona <adelinowona@gmail.com>
Date: Thu, 21 Aug 2025 00:25:45 -0400
Subject: [PATCH 9/9] update comments

---
 src/MongoDB.Driver/SortDefinitionBuilder.cs | 26 ++++++++++-----------
 1 file changed, 12 insertions(+), 14 deletions(-)

diff --git a/src/MongoDB.Driver/SortDefinitionBuilder.cs b/src/MongoDB.Driver/SortDefinitionBuilder.cs
index aa1ac09a162..a6c35841a9a 100644
--- a/src/MongoDB.Driver/SortDefinitionBuilder.cs
+++ b/src/MongoDB.Driver/SortDefinitionBuilder.cs
@@ -131,9 +131,8 @@ public static SortDefinition<TDocument> MetaTextScore<TDocument>(this SortDefini
     public sealed class SortDefinitionBuilder<TDocument>
     {
         /// <summary>
-        /// Creates a value ascending sort that sorts documents by their entire document value. For example, "$sort: 1"
-        /// This is typically used when documents are simple values (like strings, numbers, or dates)
-        /// rather than complex objects with multiple fields.
+        /// Creates an ascending sort on a value rather than on a field of a document. For example, "$sort : 1".
+        /// This is used when sorting primitive values like strings or numbers, but can also be used to sort whole documents.
         /// </summary>
         /// <returns>A value ascending sort.</returns>
         public SortDefinition<TDocument> Ascending()
@@ -142,8 +141,8 @@ public SortDefinition<TDocument> Ascending()
         }
 
         /// <summary>
-        /// Creates an ascending sort based on a specific field within the document. For example, "$sort: {field: 1}"
-        /// This is used when documents are complex objects, and you want to sort by a particular field's value.
+        /// Creates an ascending sort based on a specific field within the document. For example, "$sort : { field : 1 }".
+        /// This is used when values are documents, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>An ascending sort.</returns>
@@ -153,8 +152,8 @@ public SortDefinition<TDocument> Ascending(FieldDefinition<TDocument> field)
         }
 
         /// <summary>
-        /// Creates an ascending sort based on a specific field within the document. For example, "$sort: {field: 1}"
-        /// This is used when documents are complex objects, and you want to sort by a particular field's value.
+        /// Creates an ascending sort based on a specific field within the document. For example, "$sort : { field : 1 }".
+        /// This is used when values are documents, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>An ascending sort.</returns>
@@ -184,9 +183,8 @@ public SortDefinition<TDocument> Combine(IEnumerable<SortDefinition<TDocument>>
         }
 
         /// <summary>
-        /// Creates a value descending sort that sorts documents by their entire document value. For example, "$sort: -1"
-        /// This is typically used when documents are simple values (like strings, numbers, or dates)
-        /// rather than complex objects with multiple fields.
+        /// Creates a descending sort on a value rather than on a field of a document. For example, "$sort : -1".
+        /// This is used when sorting primitive values like strings or numbers, but can also be used to sort whole documents.
         /// </summary>
         /// <returns>A value descending sort.</returns>
         public SortDefinition<TDocument> Descending()
@@ -195,8 +193,8 @@ public SortDefinition<TDocument> Descending()
         }
 
         /// <summary>
-        /// Creates a descending sort based on a specific field within the document. For example, "$sort: {field: -1}"
-        /// This is used when documents are complex objects, and you want to sort by a particular field's value.
+        /// Creates a descending sort based on a specific field within the document. For example, "$sort: { field: -1 }".
+        /// This is used when values are documents, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>A descending sort.</returns>
@@ -206,8 +204,8 @@ public SortDefinition<TDocument> Descending(FieldDefinition<TDocument> field)
         }
 
         /// <summary>
-        /// Creates a descending sort based on a specific field within the document. For example, "$sort: {field: -1}"
-        /// This is used when documents are complex objects, and you want to sort by a particular field's value.
+        /// Creates a descending sort based on a specific field within the document. For example, "$sort: { field: -1 }".
+        /// This is used when values are documents, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>A descending sort.</returns>