SaveChanges return value docs

Improving docs on the return value of SaveChanges Issue: 2529
ErikEJ · Nov 10, 2014 · 9e43f8d · 9e43f8d
1 parent c76104c
commit 9e43f8d
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 35 deletions.
diff --git a/src/EntityFramework/Core/Objects/ObjectContext.cs b/src/EntityFramework/Core/Objects/ObjectContext.cs
@@ -2922,10 +2922,10 @@ private static int RefreshEntitiesSize(IEnumerable collection)
 
         /// <summary>Persists all updates to the database and resets change tracking in the object context.</summary>
         /// <returns>
-        /// The number of objects in an <see cref="F:System.Data.Entity.EntityState.Added" />,
-        /// <see cref="F:System.Data.Entity.EntityState.Modified" />, 
-        /// or <see cref="F:System.Data.Entity.EntityState.Deleted" /> state when
-        /// <see cref="M:System.Data.Entity.Core.Objects.ObjectContext.SaveChanges" /> was called.
+        /// The number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
         /// </returns>
         /// <exception cref="T:System.Data.Entity.Core.OptimisticConcurrencyException">An optimistic concurrency violation has occurred while saving changes.</exception>
         public virtual int SaveChanges()
@@ -2941,11 +2941,11 @@ public virtual int SaveChanges()
         /// that any asynchronous operations have completed before calling another method on this context.
         /// </remarks>
         /// <returns>
-        /// A task that represents the asynchronous operation.
-        /// The task result contains the number of objects in an <see cref="F:System.Data.Entity.EntityState.Added" />,
-        /// <see cref="F:System.Data.Entity.EntityState.Modified" />, 
-        /// or <see cref="F:System.Data.Entity.EntityState.Deleted" /> state when
-        /// <see cref="M:System.Data.Entity.Core.Objects.ObjectContext.SaveChanges" /> was called.
+        /// A task that represents the asynchronous save operation.
+        /// The task result contains the number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
         /// </returns>
         /// <exception cref="T:System.Data.Entity.Core.OptimisticConcurrencyException">An optimistic concurrency violation has occurred while saving changes.</exception>
         public virtual Task<Int32> SaveChangesAsync()
@@ -2962,11 +2962,11 @@ public virtual Task<Int32> SaveChangesAsync()
         /// A <see cref="CancellationToken" /> to observe while waiting for the task to complete.
         /// </param>
         /// <returns>
-        /// A task that represents the asynchronous operation.
-        /// The task result contains the number of objects in an <see cref="F:System.Data.Entity.EntityState.Added" />,
-        /// <see cref="F:System.Data.Entity.EntityState.Modified" />, 
-        /// or <see cref="F:System.Data.Entity.EntityState.Deleted" /> state when
-        /// <see cref="M:System.Data.Entity.Core.Objects.ObjectContext.SaveChanges" /> was called.
+        /// A task that represents the asynchronous save operation.
+        /// The task result contains the number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
         /// </returns>
         /// <exception cref="T:System.Data.Entity.Core.OptimisticConcurrencyException">An optimistic concurrency violation has occurred while saving changes.</exception>
         public virtual Task<Int32> SaveChangesAsync(CancellationToken cancellationToken)
@@ -2984,10 +2984,10 @@ public virtual Task<Int32> SaveChangesAsync(CancellationToken cancellationToken)
         /// method after <see cref="M:System.Data.Entity.Core.Objects.ObjectContext.SaveChanges(System.Boolean)" />.
         /// </param>
         /// <returns>
-        /// The number of objects in an <see cref="F:System.Data.Entity.EntityState.Added" />,
-        /// <see cref="F:System.Data.Entity.EntityState.Modified" />, 
-        /// or <see cref="F:System.Data.Entity.EntityState.Deleted" /> state when
-        /// <see cref="M:System.Data.Entity.Core.Objects.ObjectContext.SaveChanges" /> was called.
+        /// The number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
         /// </returns>
         /// <exception cref="T:System.Data.Entity.Core.OptimisticConcurrencyException">An optimistic concurrency violation has occurred while saving changes.</exception>
         [EditorBrowsable(EditorBrowsableState.Never)]
@@ -3006,10 +3006,10 @@ public virtual int SaveChanges(bool acceptChangesDuringSave)
         /// A <see cref="T:System.Data.Entity.Core.Objects.SaveOptions" /> value that determines the behavior of the operation.
         /// </param>
         /// <returns>
-        /// The number of objects in an <see cref="F:System.Data.Entity.EntityState.Added" />,
-        /// <see cref="F:System.Data.Entity.EntityState.Modified" />, 
-        /// or <see cref="F:System.Data.Entity.EntityState.Deleted" /> state when
-        /// <see cref="M:System.Data.Entity.Core.Objects.ObjectContext.SaveChanges" /> was called.
+        /// The number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
         /// </returns>
         /// <exception cref="T:System.Data.Entity.Core.OptimisticConcurrencyException">An optimistic concurrency violation has occurred while saving changes.</exception>
         public virtual int SaveChanges(SaveOptions options)
@@ -3055,11 +3055,11 @@ internal int SaveChangesInternal(SaveOptions options, bool executeInExistingTran
         /// A <see cref="T:System.Data.Entity.Core.Objects.SaveOptions" /> value that determines the behavior of the operation.
         /// </param>
         /// <returns>
-        /// A task that represents the asynchronous operation.
-        /// The task result contains the number of objects in an <see cref="F:System.Data.Entity.EntityState.Added" />,
-        /// <see cref="F:System.Data.Entity.EntityState.Modified" />, 
-        /// or <see cref="F:System.Data.Entity.EntityState.Deleted" /> state when
-        /// <see cref="M:System.Data.Entity.Core.Objects.ObjectContext.SaveChanges" /> was called.
+        /// A task that represents the asynchronous save operation.
+        /// The task result contains the number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
         /// </returns>
         /// <exception cref="T:System.Data.Entity.Core.OptimisticConcurrencyException">An optimistic concurrency violation has occurred while saving changes.</exception>
         public virtual Task<Int32> SaveChangesAsync(SaveOptions options)
@@ -3079,11 +3079,11 @@ public virtual Task<Int32> SaveChangesAsync(SaveOptions options)
         /// A <see cref="CancellationToken" /> to observe while waiting for the task to complete.
         /// </param>
         /// <returns>
-        /// A task that represents the asynchronous operation.
-        /// The task result contains the number of objects in an <see cref="F:System.Data.Entity.EntityState.Added" />,
-        /// <see cref="F:System.Data.Entity.EntityState.Modified" />, 
-        /// or <see cref="F:System.Data.Entity.EntityState.Deleted" /> state when
-        /// <see cref="M:System.Data.Entity.Core.Objects.ObjectContext.SaveChanges" /> was called.
+        /// A task that represents the asynchronous save operation.
+        /// The task result contains the number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
         /// </returns>
         /// <exception cref="T:System.Data.Entity.Core.OptimisticConcurrencyException">An optimistic concurrency violation has occurred while saving changes.</exception>
         public virtual Task<Int32> SaveChangesAsync(SaveOptions options, CancellationToken cancellationToken)

diff --git a/src/EntityFramework/DbContext.cs b/src/EntityFramework/DbContext.cs
@@ -305,7 +305,12 @@ public virtual DbSet Set(Type entityType)
         /// <summary>
         /// Saves all changes made in this context to the underlying database.
         /// </summary>
-        /// <returns> The number of objects written to the underlying database. </returns>
+        /// <returns> 
+        /// The number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
+        /// </returns>
         /// <exception cref="DbUpdateException">An error occurred sending updates to the database.</exception>
         /// <exception cref="DbUpdateConcurrencyException">
         /// A database command did not affect the expected number of rows. This usually indicates an optimistic 
@@ -338,7 +343,10 @@ public virtual int SaveChanges()
         /// </remarks>
         /// <returns>
         /// A task that represents the asynchronous save operation.
-        /// The task result contains the number of objects written to the underlying database.
+        /// The task result contains the number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
         /// </returns>
         /// <exception cref="DbUpdateException">An error occurred sending updates to the database.</exception>
         /// <exception cref="DbUpdateConcurrencyException">
@@ -373,7 +381,10 @@ public virtual Task<int> SaveChangesAsync()
         /// </param>
         /// <returns>
         /// A task that represents the asynchronous save operation.
-        /// The task result contains the number of objects written to the underlying database.
+        /// The task result contains the number of state entries written to the underlying database. This can include
+        /// state entries for entities and/or relationships. Relationship state entries are created for 
+        /// many-to-many relationships and relationships where there is no foreign key property
+        /// included in the entity class (often referred to as independent associations).
         /// </returns>
         /// <exception cref="InvalidOperationException">Thrown if the context has been disposed.</exception>
         [SuppressMessage("Microsoft.Usage", "CA1801:ReviewUnusedParameters", MessageId = "cancellationToken")]