Clarify overwrite behavior on upload methods (Azure#19110)

* Clarify overwrite behavior on upload methods

* pr feedback

Co-authored-by: jschrepp-MSFT <41338290+jschrepp-MSFT@users.noreply.github.com>

Author: jaschrep-msft

sdk/storage/Azure.Storage.Blobs/src/BlobClient.cs

@@ -273,9 +273,8 @@ protected internal virtual BlobClient WithClientSideEncryptionOptionsCore(Client
 
         #region Upload
         /// <summary>
-        /// The <see cref="Upload(Stream)"/> operation creates a new block blob
-        /// or updates the content of an existing block blob.  Updating an
-        /// existing block blob overwrites any existing metadata on the blob.
+        /// The <see cref="Upload(Stream)"/> operation
+        /// creates a new block blob or throws if the blob already exists.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -301,9 +300,8 @@ public virtual Response<BlobContentInfo> Upload(Stream content) =>
             Upload(content, CancellationToken.None);
 
         /// <summary>
-        /// The <see cref="Upload(string)"/> operation creates a new block blob
-        /// or updates the content of an existing block blob.  Updating an
-        /// existing block blob overwrites any existing metadata on the blob.
+        /// The <see cref="Upload(string)"/> operation
+        /// creates a new block blob or throws if the blob already exists.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -357,9 +355,8 @@ public virtual async Task<Response<BlobContentInfo>> UploadAsync(Stream content)
             await UploadAsync(content, CancellationToken.None).ConfigureAwait(false);
 
         /// <summary>
-        /// The <see cref="UploadAsync(string)"/> operation creates a new block blob
-        /// or updates the content of an existing block blob.  Updating an
-        /// existing block blob overwrites any existing metadata on the blob.
+        /// The <see cref="UploadAsync(string)"/> operation
+        /// creates a new block blob or throws if the blob already exists.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -386,9 +383,7 @@ public virtual async Task<Response<BlobContentInfo>> UploadAsync(string path) =>
 
         /// <summary>
         /// The <see cref="Upload(Stream, CancellationToken)"/> operation
-        /// creates a new block blob or updates the content of an existing
-        /// block blob.  Updating an existing block blob overwrites any
-        /// existing metadata on the blob.
+        /// creates a new block blob or throws if the blob already exists.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -424,9 +419,7 @@ public virtual Response<BlobContentInfo> Upload(
 
         /// <summary>
         /// The <see cref="Upload(string, CancellationToken)"/> operation
-        /// creates a new block blob or updates the content of an existing
-        /// block blob.  Updating an existing block blob overwrites any
-        /// existing metadata on the blob.
+        /// creates a new block blob or throws if the blob already exists.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -462,9 +455,7 @@ public virtual Response<BlobContentInfo> Upload(
 
         /// <summary>
         /// The <see cref="UploadAsync(Stream, CancellationToken)"/> operation
-        /// creates a new block blob or updates the content of an existing
-        /// block blob.  Updating an existing block blob overwrites any
-        /// existing metadata on the blob.
+        /// creates a new block blob or throws if the blob already exists.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -500,9 +491,7 @@ public virtual Task<Response<BlobContentInfo>> UploadAsync(
 
         /// <summary>
         /// The <see cref="UploadAsync(string, CancellationToken)"/> operation
-        /// creates a new block blob or updates the content of an existing
-        /// block blob.  Updating an existing block blob overwrites any
-        /// existing metadata on the blob.
+        /// creates a new block blob or throws if the blob already exists.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -539,9 +528,7 @@ await UploadAsync(
 
         /// <summary>
         /// The <see cref="Upload(Stream, CancellationToken)"/> operation
-        /// creates a new block blob or updates the content of an existing
-        /// block blob.  Updating an existing block blob overwrites any
-        /// existing metadata on the blob.
+        /// creates a new block blob or throws if the blob already exists.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -582,9 +569,7 @@ public virtual Response<BlobContentInfo> Upload(
 
         /// <summary>
         /// The <see cref="Upload(string, CancellationToken)"/> operation
-        /// creates a new block blob or updates the content of an existing
-        /// block blob.  Updating an existing block blob overwrites any
-        /// existing metadata on the blob.
+        /// creates a new block blob or throws if the blob already exists.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -625,9 +610,10 @@ public virtual Response<BlobContentInfo> Upload(
 
         /// <summary>
         /// The <see cref="UploadAsync(Stream, CancellationToken)"/> operation
-        /// creates a new block blob or updates the content of an existing
-        /// block blob.  Updating an existing block blob overwrites any
-        /// existing metadata on the blob.
+        /// creates a new block blob or throws if the blob already exists.
+        /// Setting <paramref name="overwrite"/> to true allows updating the
+        /// content of an existing block blob.  Updating an existing block blob
+        /// overwrites any existing metadata on the blob.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -668,9 +654,10 @@ public virtual Task<Response<BlobContentInfo>> UploadAsync(
 
         /// <summary>
         /// The <see cref="UploadAsync(string, CancellationToken)"/> operation
-        /// creates a new block blob or updates the content of an existing
-        /// block blob.  Updating an existing block blob overwrites any
-        /// existing metadata on the blob.
+        /// creates a new block blob or throws if the blob already exists.
+        /// Setting <paramref name="overwrite"/> to true allows updating the
+        /// content of an existing block blob.  Updating an existing block blob
+        /// overwrites any existing metadata on the blob.
         ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
@@ -712,10 +699,14 @@ await UploadAsync(
 
         /// <summary>
         /// The <see cref="Upload(Stream, BlobUploadOptions, CancellationToken)"/>
-        /// operation creates a new block blob or updates the content of an
-        /// existing block blob.  Updating an existing block blob overwrites
+        /// operation overwrites the contents of the blob, creating a new block
+        /// blob if none exists.  Overwriting an existing block blob replaces
         /// any existing metadata on the blob.
         ///
+        /// Set <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/specifying-conditional-headers-for-blob-service-operations">
+        /// access conditions</see> through <see cref="BlobUploadOptions.Conditions"/>
+        /// to avoid overwriting existing data.
+        ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
         /// append blobs, please see <see cref="PageBlobClient"/> or
@@ -756,10 +747,14 @@ public virtual Response<BlobContentInfo> Upload(
 
         /// <summary>
         /// The <see cref="Upload(Stream, BlobHttpHeaders, Metadata, BlobRequestConditions, IProgress{long}, AccessTier?, StorageTransferOptions, CancellationToken)"/>
-        /// operation creates a new block blob or updates the content of an
-        /// existing block blob.  Updating an existing block blob overwrites
+        /// operation overwrites the contents of the blob, creating a new block
+        /// blob if none exists.  Overwriting an existing block blob replaces
         /// any existing metadata on the blob.
         ///
+        /// Set <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/specifying-conditional-headers-for-blob-service-operations">
+        /// access conditions</see> through <see cref="BlobRequestConditions"/>
+        /// to avoid overwriting existing data.
+        ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
         /// append blobs, please see <see cref="PageBlobClient"/> or
@@ -834,10 +829,14 @@ public virtual Response<BlobContentInfo> Upload(
 
         /// <summary>
         /// The <see cref="Upload(string, BlobUploadOptions, CancellationToken)"/>
-        /// operation creates a new block blob or updates the content of an
-        /// existing block blob.  Updating an existing block blob overwrites
+        /// operation overwrites the contents of the blob, creating a new block
+        /// blob if none exists.  Overwriting an existing block blob replaces
         /// any existing metadata on the blob.
         ///
+        /// Set <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/specifying-conditional-headers-for-blob-service-operations">
+        /// access conditions</see> through <see cref="BlobUploadOptions.Conditions"/>
+        /// to avoid overwriting existing data.
+        ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
         /// append blobs, please see <see cref="PageBlobClient"/> or
@@ -883,10 +882,14 @@ public virtual Response<BlobContentInfo> Upload(
 
         /// <summary>
         /// The <see cref="Upload(string, BlobHttpHeaders, Metadata, BlobRequestConditions, IProgress{long}, AccessTier?, StorageTransferOptions, CancellationToken)"/>
-        /// operation creates a new block blob or updates the content of an
-        /// existing block blob.  Updating an existing block blob overwrites
+        /// operation overwrites the contents of the blob, creating a new block
+        /// blob if none exists.  Overwriting an existing block blob replaces
         /// any existing metadata on the blob.
         ///
+        /// Set <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/specifying-conditional-headers-for-blob-service-operations">
+        /// access conditions</see> through <see cref="BlobRequestConditions"/>
+        /// to avoid overwriting existing data.
+        ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
         /// append blobs, please see <see cref="PageBlobClient"/> or
@@ -966,10 +969,14 @@ public virtual Response<BlobContentInfo> Upload(
 
         /// <summary>
         /// The <see cref="UploadAsync(Stream, BlobHttpHeaders, Metadata, BlobRequestConditions, IProgress{long}, AccessTier?, StorageTransferOptions, CancellationToken)"/>
-        /// operation creates a new block blob or updates the content of an
-        /// existing block blob.  Updating an existing block blob overwrites
+        /// operation overwrites the contents of the blob, creating a new block
+        /// blob if none exists.  Overwriting an existing block blob replaces
         /// any existing metadata on the blob.
         ///
+        /// Set <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/specifying-conditional-headers-for-blob-service-operations">
+        /// access conditions</see> through <see cref="BlobUploadOptions.Conditions"/>
+        /// to avoid overwriting existing data.
+        ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
         /// append blobs, please see <see cref="PageBlobClient"/> or
@@ -1010,10 +1017,14 @@ await StagedUploadInternal(
 
         /// <summary>
         /// The <see cref="UploadAsync(Stream, BlobHttpHeaders, Metadata, BlobRequestConditions, IProgress{long}, AccessTier?, StorageTransferOptions, CancellationToken)"/>
-        /// operation creates a new block blob or updates the content of an
-        /// existing block blob.  Updating an existing block blob overwrites
+        /// operation overwrites the contents of the blob, creating a new block
+        /// blob if none exists.  Overwriting an existing block blob replaces
         /// any existing metadata on the blob.
         ///
+        /// Set <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/specifying-conditional-headers-for-blob-service-operations">
+        /// access conditions</see> through <see cref="BlobRequestConditions"/>
+        /// to avoid overwriting existing data.
+        ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
         /// append blobs, please see <see cref="PageBlobClient"/> or
@@ -1088,10 +1099,14 @@ public virtual Task<Response<BlobContentInfo>> UploadAsync(
 
         /// <summary>
         /// The <see cref="UploadAsync(Stream, BlobUploadOptions, CancellationToken)"/>
-        /// operation creates a new block blob or updates the content of an
-        /// existing block blob.  Updating an existing block blob overwrites
+        /// operation overwrites the contents of the blob, creating a new block
+        /// blob if none exists.  Overwriting an existing block blob replaces
         /// any existing metadata on the blob.
         ///
+        /// Set <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/specifying-conditional-headers-for-blob-service-operations">
+        /// access conditions</see> through <see cref="BlobUploadOptions.Conditions"/>
+        /// to avoid overwriting existing data.
+        ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
         /// append blobs, please see <see cref="PageBlobClient"/> or
@@ -1137,10 +1152,14 @@ public virtual async Task<Response<BlobContentInfo>> UploadAsync(
 
         /// <summary>
         /// The <see cref="UploadAsync(string, BlobHttpHeaders, Metadata, BlobRequestConditions, IProgress{long}, AccessTier?, StorageTransferOptions, CancellationToken)"/>
-        /// operation creates a new block blob or updates the content of an
-        /// existing block blob.  Updating an existing block blob overwrites
+        /// operation overwrites the contents of the blob, creating a new block
+        /// blob if none exists.  Overwriting an existing block blob replaces
         /// any existing metadata on the blob.
         ///
+        /// Set <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/specifying-conditional-headers-for-blob-service-operations">
+        /// access conditions</see> through <see cref="BlobRequestConditions"/>
+        /// to avoid overwriting existing data.
+        ///
         /// For partial block blob updates and other advanced features, please
         /// see <see cref="BlockBlobClient"/>.  To create or modify page or
         /// append blobs, please see <see cref="PageBlobClient"/> or