From 13ea4ba8fc17cc3e9dfeed21c10d2ca25c5559c8 Mon Sep 17 00:00:00 2001
From: Fabian Meiswinkel <fabianm@microsoft.com>
Date: Mon, 12 May 2025 14:11:08 +0000
Subject: [PATCH] Fix: Update session retry optimization public docs

---
 Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs        | 6 +++++-
 Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs b/Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs
index b8916711bb..ac785c8068 100644
--- a/Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs
+++ b/Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs
@@ -754,7 +754,11 @@ public Func<HttpClient> HttpClientFactory
         public AvailabilityStrategy AvailabilityStrategy { get; set; }
 
         /// <summary>
-        /// provides SessionTokenMismatchRetryPolicy optimization through customer supplied region switch hints
+        /// Provides SessionTokenMismatchRetryPolicy optimization through customer supplied region switch hints,
+        /// which guide SDK-internal retry policies on how early to fallback to the next applicable region.
+        /// With a single-write-region account the next applicable region is the write-region, with a 
+        /// multi-write-region account the next applicable region is the next region in the order of effective 
+        /// preferred regions (same order also used for read/query operations).
         /// </summary>
 #if PREVIEW
         public
diff --git a/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs b/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
index 0f4adf9f2d..f91ce44a0e 100644
--- a/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
+++ b/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
@@ -584,7 +584,11 @@ public CosmosClientBuilder WithSerializerOptions(CosmosSerializationOptions cosm
         }
 
         /// <summary>
-        /// provides SessionTokenMismatchRetryPolicy optimization through customer supplied region switch hints
+        /// Provides SessionTokenMismatchRetryPolicy optimization through customer supplied region switch hints,
+        /// which guide SDK-internal retry policies on how early to fallback to the next applicable region.
+        /// With a single-write-region account the next applicable region is the write-region, with a 
+        /// multi-write-region account the next applicable region is the next region in the order of effective 
+        /// preferred regions (same order also used for read/query operations).
         /// </summary>
         /// <param name="enableRemoteRegionPreferredForSessionRetry"></param>
         /// <returns>The <see cref="CosmosClientBuilder"/> object</returns>