Documentation: Adds additional remarks to CosmosClient (#3891)

* CosmosClient documentation improvements

* Cref fix

* Link fix

* Documentation fix

* Typo fix

---------

Co-authored-by: Matias Quaranta <ealsur@users.noreply.github.com>

Microsoft.Azure.Cosmos/src/CosmosClient.cs

@@ -92,6 +92,9 @@ 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
+    /// </remarks>
     /// <seealso cref="CosmosClientOptions"/>
     /// <seealso cref="Fluent.CosmosClientBuilder"/>
     /// <seealso href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">Performance Tips</seealso>
@@ -179,6 +182,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 +227,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 +283,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 +304,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 +383,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,

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://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.
+        /// 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://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>
@@ -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://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.
+        /// 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)
         {