Update API docs

src/EFCore.Relational/Extensions/RelationalDatabaseFacadeExtensions.cs

@@ -408,7 +408,15 @@ public static async Task<int> ExecuteSqlRawAsync(
         }
 
         /// <summary>
-        ///     Gets the underlying ADO.NET <see cref="DbConnection" /> for this <see cref="DbContext" />.
+        ///     <para>
+        ///         Gets the underlying ADO.NET <see cref="DbConnection" /> for this <see cref="DbContext" />.
+        ///     </para>
+        ///     <para>
+        ///         This connection should not be disposed if it was created by Entity Framework. Connections are created by
+        ///         Entity Framework when a connection string rather than a DbConnection object is passed to the the 'UseMyProvider'
+        ///         method for the database provider in use. Conversely, the application is responsible for disposing a DbConnection
+        ///         passed to Entity Framework in 'UseMyProvider'.
+        ///     </para>
         /// </summary>
         /// <param name="databaseFacade"> The <see cref="DatabaseFacade" /> for the context. </param>
         /// <returns> The <see cref="DbConnection" /> </returns>
@@ -605,8 +613,19 @@ public static Task<IDbContextTransaction> UseTransactionAsync(
         ///         Sets the timeout (in seconds) to use for commands executed with this <see cref="DbContext" />.
         ///     </para>
         ///     <para>
-        ///         Note that the command timeout is distinct from the connection timeout, which is commonly
-        ///         set on the database connection string.
+        ///         If this value is set, then it is used to set <see cref="DbCommand.CommandTimeout" /> whenever Entity Framework creates a
+        ///         <see cref="DbCommand" /> to execute a query.
+        ///     </para>
+        ///     <para>
+        ///         If this value is not set, then the default value used is defined by the underlying ADO.NET data provider.
+        ///         Consult the documentation for the implementation of <see cref="DbCommand" /> in the ADO.NET data provider for details of
+        ///         default values, etc.
+        ///     </para>
+        ///     <para>
+        ///         Note that the command timeout is distinct from the connection timeout. Connection timeouts are usually
+        ///         configured in the connection string. More recently, some ADO.NET data providers are adding the capability
+        ///         to also set a command timeout in the connection string. A value set with this API for the command timeout
+        ///         will override any value set in the connection string.
         ///     </para>
         /// </summary>
         /// <param name="databaseFacade"> The <see cref="DatabaseFacade" /> for the context. </param>
@@ -619,8 +638,8 @@ public static void SetCommandTimeout([NotNull] this DatabaseFacade databaseFacad
         ///         Sets the timeout to use for commands executed with this <see cref="DbContext" />.
         ///     </para>
         ///     <para>
-        ///         Note that the command timeout is distinct from the connection timeout, which is commonly
-        ///         set on the database connection string.
+        ///         This is a sugar method allowing a <see cref="TimeSpan" /> to be used to set the value. It delegates to
+        ///         <see cref="SetCommandTimeout(DatabaseFacade,Nullable{int})" />.
         ///     </para>
         /// </summary>
         /// <param name="databaseFacade"> The <see cref="DatabaseFacade" /> for the context. </param>

src/EFCore.SqlServer/Infrastructure/SqlServerDbContextOptionsBuilder.cs

@@ -14,9 +14,7 @@ namespace Microsoft.EntityFrameworkCore.Infrastructure
     ///         Allows SQL Server specific configuration to be performed on <see cref="DbContextOptions" />.
     ///     </para>
     ///     <para>
-    ///         Instances of this class are returned from a call to
-    ///         <see
-    ///             cref="SqlServerDbContextOptionsExtensions.UseSqlServer(DbContextOptionsBuilder,string,System.Action{Microsoft.EntityFrameworkCore.Infrastructure.SqlServerDbContextOptionsBuilder})" />
+    ///         Instances of this class are returned from a call to <see cref="M:SqlServerDbContextOptionsExtensions.UseSqlServer" />
     ///         and it is not designed to be directly constructed in your application code.
     ///     </para>
     /// </summary>
@@ -33,19 +31,43 @@ public SqlServerDbContextOptionsBuilder([NotNull] DbContextOptionsBuilder option
         }
 
         /// <summary>
-        ///     Configures the context to use the default retrying <see cref="IExecutionStrategy" />.
+        ///     <para>
+        ///         Configures the context to use the default retrying <see cref="IExecutionStrategy" />.
+        ///     </para>
+        ///     <para>
+        ///         This strategy is specifically tailored to SQL Server (including SQL Azure). It is pre-configured with
+        ///         error numbers for transient errors that can be retried.
+        ///     </para>
+        ///     <para>
+        ///         Default values of 6 for the maximum retry count and 30 seconds for the maximum default delay are used.
+        ///     </para>
         /// </summary>
         public virtual SqlServerDbContextOptionsBuilder EnableRetryOnFailure()
             => ExecutionStrategy(c => new SqlServerRetryingExecutionStrategy(c));
 
         /// <summary>
-        ///     Configures the context to use the default retrying <see cref="IExecutionStrategy" />.
+        ///     <para>
+        ///         Configures the context to use the default retrying <see cref="IExecutionStrategy" />.
+        ///     </para>
+        ///     <para>
+        ///         This strategy is specifically tailored to SQL Server (including SQL Azure). It is pre-configured with
+        ///         error numbers for transient errors that can be retried.
+        ///     </para>
+        ///     <para>
+        ///         A default value 30 seconds for the maximum default delay is used.
+        ///     </para>
         /// </summary>
         public virtual SqlServerDbContextOptionsBuilder EnableRetryOnFailure(int maxRetryCount)
             => ExecutionStrategy(c => new SqlServerRetryingExecutionStrategy(c, maxRetryCount));
 
         /// <summary>
-        ///     Configures the context to use the default retrying <see cref="IExecutionStrategy" />.
+        ///     <para>
+        ///         Configures the context to use the default retrying <see cref="IExecutionStrategy" />.
+        ///     </para>
+        ///     <para>
+        ///         This strategy is specifically tailored to SQL Server (including SQL Azure). It is pre-configured with
+        ///         error numbers for transient errors that can be retried, but additional error numbers can also be supplied.
+        ///     </para>
         /// </summary>
         /// <param name="maxRetryCount"> The maximum number of retry attempts. </param>
         /// <param name="maxRetryDelay"> The maximum delay between retries. </param>

src/EFCore.SqlServer/Migrations/SqlServerMigrationsSqlGenerator.cs

@@ -79,8 +79,8 @@ public override IReadOnlyList<MigrationCommand> Generate(
         ///         <see cref="MigrationCommandListBuilder" />.
         ///     </para>
         ///     <para>
-        ///         This method uses a double-dispatch mechanism to call one of the 'Generate' methods that are
-        ///         specific to a certain subtype of <see cref="MigrationOperation" />. Typically database providers
+        ///         This method uses a double-dispatch mechanism to call the <see cref="M:MigrationsSqlGenerator.Generate" /> method
+        ///         that is specific to a certain subtype of <see cref="MigrationOperation" />. Typically database providers
         ///         will override these specific methods rather than this method. However, providers can override
         ///         this methods to handle provider-specific operations.
         ///     </para>

src/EFCore.SqlServer/SqlServerRetryingExecutionStrategy.cs

@@ -12,28 +12,40 @@
 namespace Microsoft.EntityFrameworkCore
 {
     /// <summary>
-    ///     An <see cref="IExecutionStrategy" /> implementation for retrying failed executions
-    ///     on SQL Server.
+    ///     <para>
+    ///         An <see cref="IExecutionStrategy" /> implementation for retrying failed executions on SQL Server.
+    ///     </para>
+    ///     <para>
+    ///         This strategy is specifically tailored to SQL Server (including SQL Azure). It is pre-configured with
+    ///         error numbers for transient errors that can be retried. Additional error numbers to retry on can also be supplied.
+    ///     </para>
     /// </summary>
     public class SqlServerRetryingExecutionStrategy : ExecutionStrategy
     {
         private readonly ICollection<int> _additionalErrorNumbers;
 
         /// <summary>
-        ///     Creates a new instance of <see cref="SqlServerRetryingExecutionStrategy" />.
+        ///     <para>
+        ///         Creates a new instance of <see cref="SqlServerRetryingExecutionStrategy" />.
+        ///     </para>
+        ///     <para>
+        ///         Default values of 6 for the maximum retry count and 30 seconds for the maximum default delay are used.
+        ///     </para>
         /// </summary>
         /// <param name="context"> The context on which the operations will be invoked. </param>
-        /// <remarks>
-        ///     The default retry limit is 6, which means that the total amount of time spent before failing is about a minute.
-        /// </remarks>
         public SqlServerRetryingExecutionStrategy(
             [NotNull] DbContext context)
             : this(context, DefaultMaxRetryCount)
         {
         }
 
         /// <summary>
-        ///     Creates a new instance of <see cref="SqlServerRetryingExecutionStrategy" />.
+        ///     <para>
+        ///         Creates a new instance of <see cref="SqlServerRetryingExecutionStrategy" />.
+        ///     </para>
+        ///     <para>
+        ///         Default values of 6 for the maximum retry count and 30 seconds for the maximum default delay are used.
+        ///     </para>
         /// </summary>
         /// <param name="dependencies"> Parameter object containing service dependencies. </param>
         public SqlServerRetryingExecutionStrategy(
@@ -43,7 +55,12 @@ public SqlServerRetryingExecutionStrategy(
         }
 
         /// <summary>
-        ///     Creates a new instance of <see cref="SqlServerRetryingExecutionStrategy" />.
+        ///     <para>
+        ///         Creates a new instance of <see cref="SqlServerRetryingExecutionStrategy" />.
+        ///     </para>
+        ///     <para>
+        ///         A default value 30 seconds for the maximum default delay is used.
+        ///     </para>
         /// </summary>
         /// <param name="context"> The context on which the operations will be invoked. </param>
         /// <param name="maxRetryCount"> The maximum number of retry attempts. </param>
@@ -55,7 +72,12 @@ public SqlServerRetryingExecutionStrategy(
         }
 
         /// <summary>
-        ///     Creates a new instance of <see cref="SqlServerRetryingExecutionStrategy" />.
+        ///     <para>
+        ///         Creates a new instance of <see cref="SqlServerRetryingExecutionStrategy" />.
+        ///     </para>
+        ///     <para>
+        ///         A default value 30 seconds for the maximum default delay is used.
+        ///     </para>
         /// </summary>
         /// <param name="dependencies"> Parameter object containing service dependencies. </param>
         /// <param name="maxRetryCount"> The maximum number of retry attempts. </param>

src/EFCore/ChangeTracking/ChangeTracker.cs

@@ -153,8 +153,19 @@ public virtual CascadeTiming CascadeDeleteTiming
         }
 
         /// <summary>
-        ///     Gets an <see cref="EntityEntry" /> for each entity being tracked by the context.
-        ///     The entries provide access to change tracking information and operations for each entity.
+        ///     <para>
+        ///         Returns an <see cref="EntityEntry" /> for each entity being tracked by the context.
+        ///         The entries provide access to change tracking information and operations for each entity.
+        ///     </para>
+        ///     <para>
+        ///         This method calls <see cref="DetectChanges" /> to ensure all entries returned reflect up-to-date state.
+        ///         Use <see cref="AutoDetectChangesEnabled" /> to prevent DetectChanges from being called automatically.
+        ///     </para>
+        ///     <para>
+        ///         Note that modification of entity state while iterating over the returned enumeration may result in
+        ///         an <see cref="InvalidOperationException" /> indicating that the collection was modified while enumerating.
+        ///         To avoid this, create a defensive copy using <see cref="Enumerable.ToList{TSource}" /> or similar before iterating.
+        ///     </para>
         /// </summary>
         /// <returns> An entry for each entity being tracked. </returns>
         public virtual IEnumerable<EntityEntry> Entries()

src/EFCore/ChangeTracking/EntityEntryGraphNode.cs

@@ -11,8 +11,13 @@
 namespace Microsoft.EntityFrameworkCore.ChangeTracking
 {
     /// <summary>
-    ///     Provides access to change tracking information and operations for a node in a
-    ///     graph of entities that is being traversed.
+    ///     <para>
+    ///         Provides access to change tracking information and operations for a node in a
+    ///         graph of entities that is being traversed.
+    ///     </para>
+    ///     <para>
+    ///         See <see cref="M:ChangeTracker.TrackGraph" /> for information on how graph nodes are used.
+    ///     </para>
     /// </summary>
     public class EntityEntryGraphNode : IInfrastructure<InternalEntityEntry>
     {
@@ -40,18 +45,34 @@ public EntityEntryGraphNode(
         }
 
         /// <summary>
-        ///     Gets the entry tracking information about this entity.
+        ///     <para>
+        ///         An <see cref="EntityEntry" /> for the entity instance from which a navigation property was traversed to the the instance
+        ///         represented by this node.
+        ///     </para>
+        ///     <para>
+        ///         See <see cref="M:ChangeTracker.TrackGraph" /> for information on how graph nodes are used.
+        ///     </para>
         /// </summary>
         public virtual EntityEntry SourceEntry
             => _sourceEntry == null ? null : new EntityEntry(_sourceEntry);
 
         /// <summary>
-        ///     Gets the navigation property that is being traversed to reach this node in the graph.
+        ///     <para>
+        ///         Gets the navigation property that is being traversed to reach this node in the graph.
+        ///     </para>
+        ///     <para>
+        ///         See <see cref="M:ChangeTracker.TrackGraph" /> for information on how graph nodes are used.
+        ///     </para>
         /// </summary>
         public virtual INavigationBase InboundNavigation { get; }
 
         /// <summary>
-        ///     Gets the entry tracking information about this entity.
+        ///     <para>
+        ///         An <see cref="EntityEntry" /> for the entity instance represented by this node.
+        ///     </para>
+        ///     <para>
+        ///         See <see cref="M:ChangeTracker.TrackGraph" /> for information on how graph nodes are used.
+        ///     </para>
         /// </summary>
         public virtual EntityEntry Entry
             => new EntityEntry(_entry);
@@ -65,6 +86,7 @@ public virtual EntityEntry Entry
         ///         application code.
         ///     </para>
         /// </summary>
+        [EntityFrameworkInternal]
         InternalEntityEntry IInfrastructure<InternalEntityEntry>.Instance
             => _entry;
 

src/EFCore/DbContextOptionsBuilder`.cs

@@ -69,8 +69,8 @@ public DbContextOptionsBuilder([NotNull] DbContextOptions<TContext> options)
         ///         for logging done by this context.
         ///     </para>
         ///     <para>
-        ///         There is no need to call this method when using one of the 'AddDbContext' methods.
-        ///         'AddDbContext' will ensure that the <see cref="ILoggerFactory" /> used by EF is obtained from the
+        ///         There is no need to call this method when using one of the <see cref="M:EntityFrameworkServiceCollectionExtensions.AddDbContext" />
+        ///         methods. 'AddDbContext' will ensure that the <see cref="ILoggerFactory" /> used by EF is obtained from the
         ///         application service provider.
         ///     </para>
         ///     <para>

src/EFCore/DbSet.cs

@@ -92,6 +92,10 @@ public virtual IQueryable<TEntity> AsQueryable()
         ///         <see cref="LocalView{TEntity}.ToObservableCollection" /> for WPF binding, or
         ///         <see cref="LocalView{TEntity}.ToBindingList" /> for WinForms.
         ///     </para>
+        ///     <para>
+        ///         Note that this method calls <see cref="ChangeTracker.DetectChanges" /> unless
+        ///         <see cref="ChangeTracker.AutoDetectChangesEnabled" /> has been set to <see langword="false" />.
+        ///     </para>
         /// </summary>
         public virtual LocalView<TEntity> Local
             => throw new NotImplementedException();

src/EFCore/Diagnostics/InterceptionResult.cs

@@ -5,7 +5,7 @@ namespace Microsoft.EntityFrameworkCore.Diagnostics
 {
     /// <summary>
     ///     <para>
-    ///         Represents a result from an <see cref="IInterceptor" /> such as an 'IDbConnectionInterceptor' to allow
+    ///         Represents a result from an <see cref="IInterceptor" /> such as an <see cref="ISaveChangesInterceptor" /> to allow
     ///         suppression of the normal operation being intercepted.
     ///     </para>
     ///     <para>

src/EFCore/Diagnostics/InterceptionResult`.cs

@@ -8,7 +8,7 @@ namespace Microsoft.EntityFrameworkCore.Diagnostics
 {
     /// <summary>
     ///     <para>
-    ///         Represents a result from an <see cref="IInterceptor" /> such as an 'IDbCommandInterceptor' to allow
+    ///         Represents a result from an <see cref="IInterceptor" /> such as an <see cref="ISaveChangesInterceptor" /> to allow
     ///         suppression of the normal operation being intercepted.
     ///     </para>
     ///     <para>