Add exception documentation for SaveChanges

Issue #7012

Text is copied from the documentation for the exception types.
Also checked that there are no other custom exception types used at runtime that do not have similar documentation. All other exceptions indicate a program/logic error, not a recoverable state, and use built-in exception types.

src/EFCore.Relational/Extensions/RelationalExecutionStrategyExtensions.cs

@@ -26,7 +26,7 @@ public static class RelationalExecutionStrategyExtensions
         ///     transaction was being committed.
         /// </param>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static void ExecuteInTransaction(
             [NotNull] this IExecutionStrategy strategy,
@@ -54,7 +54,7 @@ public static void ExecuteInTransaction(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task ExecuteInTransactionAsync(
             [NotNull] this IExecutionStrategy strategy,
@@ -86,7 +86,7 @@ public static Task ExecuteInTransactionAsync(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task ExecuteInTransactionAsync(
             [NotNull] this IExecutionStrategy strategy,
@@ -112,7 +112,7 @@ public static Task ExecuteInTransactionAsync(
         /// <typeparam name="TResult"> The return type of <paramref name="operation" />. </typeparam>
         /// <returns> The result from the operation. </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static TResult ExecuteInTransaction<TResult>(
             [NotNull] this IExecutionStrategy strategy,
@@ -145,7 +145,7 @@ public static TResult ExecuteInTransaction<TResult>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task<TResult> ExecuteInTransactionAsync<TResult>(
             [NotNull] this IExecutionStrategy strategy,
@@ -172,7 +172,7 @@ public static Task<TResult> ExecuteInTransactionAsync<TResult>(
         /// <param name="isolationLevel"> The isolation level to use for the transaction. </param>
         /// <typeparam name="TState"> The type of the state. </typeparam>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static void ExecuteInTransaction<TState>(
             [NotNull] this IExecutionStrategy strategy,
@@ -212,7 +212,7 @@ public static void ExecuteInTransaction<TState>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task ExecuteInTransactionAsync<TState>(
             [NotNull] this IExecutionStrategy strategy,
@@ -246,7 +246,7 @@ public static Task ExecuteInTransactionAsync<TState>(
         /// <typeparam name="TResult"> The return type of <paramref name="operation" />. </typeparam>
         /// <returns> The result from the operation. </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static TResult ExecuteInTransaction<TState, TResult>(
             [NotNull] this IExecutionStrategy strategy,
@@ -283,7 +283,7 @@ public static TResult ExecuteInTransaction<TState, TResult>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task<TResult> ExecuteInTransactionAsync<TState, TResult>(
             [NotNull] this IExecutionStrategy strategy,

src/EFCore/DbContext.cs

@@ -319,6 +319,14 @@ protected internal virtual void OnModelCreating(ModelBuilder modelBuilder)
         /// <returns>
         ///     The number of state entries written to the database.
         /// </returns>
+        /// <exception cref="DbUpdateException">
+        ///     An error is encountered while saving to the database.
+        /// </exception>
+        /// <exception cref="DbUpdateConcurrencyException">
+        ///     A concurrency violation is encountered while saving to the database. 
+        ///     A concurrency violation occurs when an unexpected number of rows are affected during save. 
+        ///     This is usually because the data in the database has been modified since it was loaded into memory.
+        /// </exception>
         [DebuggerStepThrough]
         public virtual int SaveChanges() => SaveChanges(acceptAllChangesOnSuccess: true);
 
@@ -337,6 +345,14 @@ protected internal virtual void OnModelCreating(ModelBuilder modelBuilder)
         /// <returns>
         ///     The number of state entries written to the database.
         /// </returns>
+        /// <exception cref="DbUpdateException">
+        ///     An error is encountered while saving to the database.
+        /// </exception>
+        /// <exception cref="DbUpdateConcurrencyException">
+        ///     A concurrency violation is encountered while saving to the database. 
+        ///     A concurrency violation occurs when an unexpected number of rows are affected during save. 
+        ///     This is usually because the data in the database has been modified since it was loaded into memory.
+        /// </exception>
         [DebuggerStepThrough]
         public virtual int SaveChanges(bool acceptAllChangesOnSuccess)
         {
@@ -383,6 +399,14 @@ private void TryDetectChanges()
         ///     A task that represents the asynchronous save operation. The task result contains the
         ///     number of state entries written to the database.
         /// </returns>
+        /// <exception cref="DbUpdateException">
+        ///     An error is encountered while saving to the database.
+        /// </exception>
+        /// <exception cref="DbUpdateConcurrencyException">
+        ///     A concurrency violation is encountered while saving to the database. 
+        ///     A concurrency violation occurs when an unexpected number of rows are affected during save. 
+        ///     This is usually because the data in the database has been modified since it was loaded into memory.
+        /// </exception>
         public virtual Task<int> SaveChangesAsync(CancellationToken cancellationToken = default(CancellationToken))
             => SaveChangesAsync(acceptAllChangesOnSuccess: true, cancellationToken: cancellationToken);
 
@@ -409,6 +433,14 @@ private void TryDetectChanges()
         ///     A task that represents the asynchronous save operation. The task result contains the
         ///     number of state entries written to the database.
         /// </returns>
+        /// <exception cref="DbUpdateException">
+        ///     An error is encountered while saving to the database.
+        /// </exception>
+        /// <exception cref="DbUpdateConcurrencyException">
+        ///     A concurrency violation is encountered while saving to the database. 
+        ///     A concurrency violation occurs when an unexpected number of rows are affected during save. 
+        ///     This is usually because the data in the database has been modified since it was loaded into memory.
+        /// </exception>
         public virtual async Task<int> SaveChangesAsync(bool acceptAllChangesOnSuccess,
             CancellationToken cancellationToken = default(CancellationToken))
         {

src/EFCore/Extensions/ExecutionStrategyExtensions.cs

@@ -319,7 +319,7 @@ public static Task<TResult> ExecuteAsync<TState, TResult>(
         /// <typeparam name="TResult"> The return type of <paramref name="operation" />. </typeparam>
         /// <returns> The result from the operation. </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static TResult Execute<TState, TResult>(
             [NotNull] this IExecutionStrategy strategy,
@@ -352,7 +352,7 @@ public static TResult Execute<TState, TResult>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task<TResult> ExecuteAsync<TState, TResult>(
             [NotNull] this IExecutionStrategy strategy,
@@ -380,7 +380,7 @@ public static Task<TResult> ExecuteAsync<TState, TResult>(
         ///     transaction was being committed.
         /// </param>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static void ExecuteInTransaction(
             [NotNull] this IExecutionStrategy strategy,
@@ -406,7 +406,7 @@ public static void ExecuteInTransaction(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task ExecuteInTransactionAsync(
             [NotNull] this IExecutionStrategy strategy,
@@ -436,7 +436,7 @@ public static Task ExecuteInTransactionAsync(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task ExecuteInTransactionAsync(
             [NotNull] this IExecutionStrategy strategy,
@@ -460,7 +460,7 @@ public static Task ExecuteInTransactionAsync(
         /// <typeparam name="TResult"> The return type of <paramref name="operation" />. </typeparam>
         /// <returns> The result from the operation. </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static TResult ExecuteInTransaction<TResult>(
             [NotNull] this IExecutionStrategy strategy,
@@ -491,7 +491,7 @@ public static TResult ExecuteInTransaction<TResult>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task<TResult> ExecuteInTransactionAsync<TResult>(
             [NotNull] this IExecutionStrategy strategy,
@@ -515,7 +515,7 @@ public static Task<TResult> ExecuteInTransactionAsync<TResult>(
         /// </param>
         /// <typeparam name="TState"> The type of the state. </typeparam>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static void ExecuteInTransaction<TState>(
             [NotNull] this IExecutionStrategy strategy,
@@ -552,7 +552,7 @@ public static void ExecuteInTransaction<TState>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task ExecuteInTransactionAsync<TState>(
             [NotNull] this IExecutionStrategy strategy,
@@ -583,7 +583,7 @@ public static Task ExecuteInTransactionAsync<TState>(
         /// <typeparam name="TResult"> The return type of <paramref name="operation" />. </typeparam>
         /// <returns> The result from the operation. </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static TResult ExecuteInTransaction<TState, TResult>(
             [NotNull] this IExecutionStrategy strategy,
@@ -620,7 +620,7 @@ public static TResult ExecuteInTransaction<TState, TResult>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task<TResult> ExecuteInTransactionAsync<TState, TResult>(
             [NotNull] this IExecutionStrategy strategy,
@@ -652,7 +652,7 @@ public static Task<TResult> ExecuteInTransactionAsync<TState, TResult>(
         /// <typeparam name="TResult"> The return type of <paramref name="operation" />. </typeparam>
         /// <returns> The result from the operation. </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static TResult ExecuteInTransaction<TState, TResult>(
             [NotNull] IExecutionStrategy strategy,
@@ -702,7 +702,7 @@ public static TResult ExecuteInTransaction<TState, TResult>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public static Task<TResult> ExecuteInTransactionAsync<TState, TResult>(
             [NotNull] IExecutionStrategy strategy,

src/EFCore/Storage/ExecutionStrategy.cs

@@ -137,7 +137,7 @@ protected static bool Suspended
         /// <typeparam name="TResult"> The return type of <paramref name="operation" />. </typeparam>
         /// <returns> The result from the operation. </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public virtual TResult Execute<TState, TResult>(
             TState state,
@@ -227,7 +227,7 @@ private TResult ExecuteImplementation<TState, TResult>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         public virtual Task<TResult> ExecuteAsync<TState, TResult>(
             TState state,

src/EFCore/Storage/IExecutionStrategy.cs

@@ -30,7 +30,7 @@ public interface IExecutionStrategy
         /// <typeparam name="TResult"> The return type of <paramref name="operation" />. </typeparam>
         /// <returns> The result from the operation. </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         TResult Execute<TState, TResult>(
             [CanBeNull] TState state,
@@ -57,7 +57,7 @@ TResult Execute<TState, TResult>(
         ///     the retry limit is reached, the returned task will become faulted and the exception must be observed.
         /// </returns>
         /// <exception cref="RetryLimitExceededException">
-        ///     Thrown if the operation has not succeeded after the configured number of retries.
+        ///     The operation has not succeeded after the configured number of retries.
         /// </exception>
         Task<TResult> ExecuteAsync<TState, TResult>(
             [CanBeNull] TState state,