From 4cac2d4fdde4eb3cb001f010ead6ae7add9b294c Mon Sep 17 00:00:00 2001
From: Rinat Minibaev <132935507+rinatmini@users.noreply.github.com>
Date: Fri, 2 Jun 2023 16:26:54 -0700
Subject: [PATCH 1/5] CosmosClient documentation improvements

---
 Microsoft.Azure.Cosmos/src/CosmosClient.cs    | 25 ++++++++++++++++++-
 .../src/Fluent/CosmosClientBuilder.cs         | 13 ++++++++++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/Microsoft.Azure.Cosmos/src/CosmosClient.cs b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
index d4fe7dcb9b..342e00ab37 100644
--- a/Microsoft.Azure.Cosmos/src/CosmosClient.cs
+++ b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
@@ -92,6 +92,14 @@ namespace Microsoft.Azure.Cosmos
     /// ]]>
     /// </code>
     /// </example>
+    /// <remarks>
+    /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls, 
+    /// except the initialization cases when the SDK warms up the caches and connections before the first call to the service is made 
+    /// (<see cref="CosmosClient.CreateAndInitializeAsync(string, Azure.AzureKeyCredential, System.Collections.Generic.IReadOnlyList{ValueTuple{string, string}}, CosmosClientOptions, System.Threading.CancellationToken)"/>, 
+    /// <see cref="CosmosClient.CreateAndInitializeAsync(string, Azure.Core.TokenCredential, System.Collections.Generic.IReadOnlyList{ValueTuple{string, string}}, CosmosClientOptions, System.Threading.CancellationToken)"/>, 
+    /// <see cref="CosmosClient.CreateAndInitializeAsync(string, string, System.Collections.Generic.IReadOnlyList{ValueTuple{string, string}}, CosmosClientOptions, System.Threading.CancellationToken)"/>, 
+    /// <see cref="CosmosClient.CreateAndInitializeAsync(string, System.Collections.Generic.IReadOnlyList{ValueTuple{string, string}}, CosmosClientOptions, System.Threading.CancellationToken)"/>).
+    /// </remarks>
     /// <seealso cref="CosmosClientOptions"/>
     /// <seealso cref="Fluent.CosmosClientBuilder"/>
     /// <seealso href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">Performance Tips</seealso>
@@ -179,6 +187,9 @@ protected CosmosClient()
         /// ]]>
         /// </code>
         /// </example>
+        /// <remarks>
+        /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
+        /// </remarks>
         /// <seealso cref="CosmosClientOptions"/>
         /// <seealso cref="Fluent.CosmosClientBuilder"/>
         /// <seealso href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">Performance Tips</seealso>
@@ -221,6 +232,9 @@ public CosmosClient(
         /// ]]>
         /// </code>
         /// </example>
+        /// <remarks>
+        /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
+        /// </remarks>
         /// <seealso cref="CosmosClientOptions"/>
         /// <seealso cref="Fluent.CosmosClientBuilder"/>
         /// <seealso href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">Performance Tips</seealso>
@@ -274,7 +288,10 @@ public CosmosClient(
         /// <seealso cref="Fluent.CosmosClientBuilder"/>
         /// <seealso href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">Performance Tips</seealso>
         /// <seealso href="https://docs.microsoft.com/azure/cosmos-db/troubleshoot-dot-net-sdk">Diagnose and troubleshoot issues</seealso>
-        /// <remarks>AzureKeyCredential enables changing/updating master-key/ResourceToken whle CosmosClient is still in use.</remarks>
+        /// <remarks>
+        /// AzureKeyCredential enables changing/updating master-key/ResourceToken whle CosmosClient is still in use.
+        /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
+        /// </remarks>
         public CosmosClient(
             string accountEndpoint,
             AzureKeyCredential authKeyOrResourceTokenCredential,
@@ -292,6 +309,9 @@ public CosmosClient(
         /// of the application which enables efficient connection management and performance. Please refer to the
         /// <see href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">performance guide</see>.
         /// </summary>
+        /// <remarks>
+        /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
+        /// </remarks>
         /// <param name="accountEndpoint">The cosmos service endpoint to use.</param>
         /// <param name="tokenCredential"><see cref="TokenCredential"/>The token to provide AAD token for authorization.</param>
         /// <param name="clientOptions">(Optional) client options</param>
@@ -368,6 +388,9 @@ internal CosmosClient(
         /// ]]>
         /// </code>
         /// </example>
+        /// <remarks>
+        /// The returned reference doesn't guarantee credentials or connectivity validations because initialization doesn't make any network calls.
+        /// </remarks>
         public static async Task<CosmosClient> CreateAndInitializeAsync(string accountEndpoint,
                                                                         string authKeyOrResourceToken,
                                                                         IReadOnlyList<(string databaseId, string containerId)> containers,
diff --git a/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs b/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
index 692d5b498a..1bf077c918 100644
--- a/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
+++ b/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
@@ -167,9 +167,13 @@ public CosmosClientBuilder(
 
         /// <summary>
         /// A method to create the cosmos client
+        /// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime 
+        /// of the application which enables efficient connection management and performance. Please refer to the
+        /// <see href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">performance guide</see>.
         /// </summary>
         /// <remarks>
         /// Setting this property after sending any request won't have any effect.
+        /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
         /// </remarks>
         /// <returns>An instance of <see cref="CosmosClient"/>.</returns>
         public CosmosClient Build()
@@ -191,6 +195,11 @@ public CosmosClient Build()
 
         /// <summary>
         /// A method to create the cosmos client and initialize the provided containers.
+        /// In addition to that it initializes the client with containers provided i.e The SDK warms up the caches and 
+        /// connections before the first call to the service is made. Use this to obtain lower latency while startup of your application.
+        /// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime 
+        /// of the application which enables efficient connection management and performance. Please refer to the
+        /// <see href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">performance guide</see>.
         /// </summary>
         /// <param name="containers">Containers to be initialized identified by it's database name and container name.</param>
         /// <param name="cancellationToken">(Optional) Cancellation Token</param>
@@ -214,9 +223,13 @@ public Task<CosmosClient> BuildAndInitializeAsync(IReadOnlyList<(string database
 
         /// <summary>
         /// A method to create the cosmos client
+        /// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime 
+        /// of the application which enables efficient connection management and performance. Please refer to the
+        /// <see href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">performance guide</see>.
         /// </summary>
         /// <remarks>
         /// Setting this property after sending any request won't have any effect.
+        /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
         /// </remarks>
         internal virtual CosmosClient Build(DocumentClient documentClient)
         {

From f2a0fba9e8c5af9fab69af9fdcf690c09662c413 Mon Sep 17 00:00:00 2001
From: Rinat Minibaev <132935507+rinatmini@users.noreply.github.com>
Date: Fri, 2 Jun 2023 16:35:51 -0700
Subject: [PATCH 2/5] Cref fix

---
 Microsoft.Azure.Cosmos/src/CosmosClient.cs | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/Microsoft.Azure.Cosmos/src/CosmosClient.cs b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
index 342e00ab37..917014afde 100644
--- a/Microsoft.Azure.Cosmos/src/CosmosClient.cs
+++ b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
@@ -94,11 +94,7 @@ namespace Microsoft.Azure.Cosmos
     /// </example>
     /// <remarks>
     /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls, 
-    /// except the initialization cases when the SDK warms up the caches and connections before the first call to the service is made 
-    /// (<see cref="CosmosClient.CreateAndInitializeAsync(string, Azure.AzureKeyCredential, System.Collections.Generic.IReadOnlyList{ValueTuple{string, string}}, CosmosClientOptions, System.Threading.CancellationToken)"/>, 
-    /// <see cref="CosmosClient.CreateAndInitializeAsync(string, Azure.Core.TokenCredential, System.Collections.Generic.IReadOnlyList{ValueTuple{string, string}}, CosmosClientOptions, System.Threading.CancellationToken)"/>, 
-    /// <see cref="CosmosClient.CreateAndInitializeAsync(string, string, System.Collections.Generic.IReadOnlyList{ValueTuple{string, string}}, CosmosClientOptions, System.Threading.CancellationToken)"/>, 
-    /// <see cref="CosmosClient.CreateAndInitializeAsync(string, System.Collections.Generic.IReadOnlyList{ValueTuple{string, string}}, CosmosClientOptions, System.Threading.CancellationToken)"/>).
+    /// except the initialization cases when the SDK warms up the caches and connections before the first call to the service is made (CosmosClient.CreateAndInitializeAsync calls).
     /// </remarks>
     /// <seealso cref="CosmosClientOptions"/>
     /// <seealso cref="Fluent.CosmosClientBuilder"/>

From f411f3590354cafc1fd8cc28732cf73eaf3e3ee7 Mon Sep 17 00:00:00 2001
From: Rinat Minibaev <132935507+rinatmini@users.noreply.github.com>
Date: Mon, 5 Jun 2023 11:43:29 -0700
Subject: [PATCH 3/5] Link fix

---
 Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs b/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
index 1bf077c918..8b72bfffa4 100644
--- a/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
+++ b/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
@@ -169,7 +169,7 @@ public CosmosClientBuilder(
         /// A method to create the cosmos client
         /// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime 
         /// of the application which enables efficient connection management and performance. Please refer to the
-        /// <see href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">performance guide</see>.
+        /// <see href="https://learn.microsoft.com/azure/cosmos-db/nosql/performance-tips-dotnet-sdk-v3">performance guide</see>.
         /// </summary>
         /// <remarks>
         /// Setting this property after sending any request won't have any effect.
@@ -199,7 +199,7 @@ public CosmosClient Build()
         /// connections before the first call to the service is made. Use this to obtain lower latency while startup of your application.
         /// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime 
         /// of the application which enables efficient connection management and performance. Please refer to the
-        /// <see href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">performance guide</see>.
+        /// <see href="https://learn.microsoft.com/azure/cosmos-db/nosql/performance-tips-dotnet-sdk-v3">performance guide</see>.
         /// </summary>
         /// <param name="containers">Containers to be initialized identified by it's database name and container name.</param>
         /// <param name="cancellationToken">(Optional) Cancellation Token</param>
@@ -225,7 +225,7 @@ public Task<CosmosClient> BuildAndInitializeAsync(IReadOnlyList<(string database
         /// A method to create the cosmos client
         /// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime 
         /// of the application which enables efficient connection management and performance. Please refer to the
-        /// <see href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">performance guide</see>.
+        /// <see href="https://learn.microsoft.com/azure/cosmos-db/nosql/performance-tips-dotnet-sdk-v3">performance guide</see>.
         /// </summary>
         /// <remarks>
         /// Setting this property after sending any request won't have any effect.

From dbcc8f6cd7fb2a07cd531e222d5e96136317341e Mon Sep 17 00:00:00 2001
From: Rinat Minibaev <132935507+rinatmini@users.noreply.github.com>
Date: Wed, 7 Jun 2023 17:03:47 -0700
Subject: [PATCH 4/5] Documentation fix

---
 Microsoft.Azure.Cosmos/src/CosmosClient.cs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Microsoft.Azure.Cosmos/src/CosmosClient.cs b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
index 917014afde..93cb03afd5 100644
--- a/Microsoft.Azure.Cosmos/src/CosmosClient.cs
+++ b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
@@ -93,8 +93,7 @@ namespace Microsoft.Azure.Cosmos
     /// </code>
     /// </example>
     /// <remarks>
-    /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls, 
-    /// except the initialization cases when the SDK warms up the caches and connections before the first call to the service is made (CosmosClient.CreateAndInitializeAsync calls).
+    /// The returned not-initialized reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls, 
     /// </remarks>
     /// <seealso cref="CosmosClientOptions"/>
     /// <seealso cref="Fluent.CosmosClientBuilder"/>

From a587fe8b55bb75587d9252e5c8ec6c3387e74db2 Mon Sep 17 00:00:00 2001
From: Rinat Minibaev <132935507+rinatmini@users.noreply.github.com>
Date: Wed, 7 Jun 2023 17:07:13 -0700
Subject: [PATCH 5/5] Typo fix

---
 Microsoft.Azure.Cosmos/src/CosmosClient.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Microsoft.Azure.Cosmos/src/CosmosClient.cs b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
index 93cb03afd5..d622e9ddcb 100644
--- a/Microsoft.Azure.Cosmos/src/CosmosClient.cs
+++ b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
@@ -93,7 +93,7 @@ namespace Microsoft.Azure.Cosmos
     /// </code>
     /// </example>
     /// <remarks>
-    /// The returned not-initialized reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls, 
+    /// The returned not-initialized reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls
     /// </remarks>
     /// <seealso cref="CosmosClientOptions"/>
     /// <seealso cref="Fluent.CosmosClientBuilder"/>