Use remarks in XML docs (#26439)

Co-authored-by: Shay Rojansky <roji@roji.org>

src/EFCore.Abstractions/ChangeTracking/ObservableCollectionListSource.cs

@@ -9,9 +9,9 @@
 namespace Microsoft.EntityFrameworkCore.ChangeTracking
 {
     /// <summary>
-    ///     <para>
-    ///         Extends <see cref="ObservableCollection{T}" /> and adds an explicit implementation of <see cref="IListSource" />.
-    ///     </para>
+    ///     Extends <see cref="ObservableCollection{T}" /> and adds an explicit implementation of <see cref="IListSource" />.
+    /// </summary>
+    /// <remarks>
     ///     <para>
     ///         The method <see cref="IListSource.GetList" /> is implemented to return an <see cref="IBindingList" />
     ///         implementation that stays in sync with the ObservableCollection.
@@ -20,9 +20,9 @@ namespace Microsoft.EntityFrameworkCore.ChangeTracking
     ///         This class can be used to implement navigation properties on entities for use in Windows Forms data binding.
     ///         For WPF data binding use an ObservableCollection rather than an instance of this class.
     ///     </para>
-    /// </summary>
-    /// <remarks>
-    ///     See <see href="https://aka.ms/efcore-docs-local-views">Local views of tracked entities in EF Core</see> for more information.
+    ///     <para>
+    ///         See <see href="https://aka.ms/efcore-docs-local-views">Local views of tracked entities in EF Core</see> for more information.
+    ///     </para>
     /// </remarks>
     /// <typeparam name="T">The type of elements in the collection.</typeparam>
     public class ObservableCollectionListSource<T> : ObservableCollection<T>, IListSource

src/EFCore.Abstractions/Infrastructure/ILazyLoader.cs

@@ -9,19 +9,19 @@
 namespace Microsoft.EntityFrameworkCore.Infrastructure
 {
     /// <summary>
-    ///     <para>
-    ///         A service that can be injected into entities to give them the capability
-    ///         of loading navigation properties automatically the first time they are accessed.
-    ///     </para>
+    ///     A service that can be injected into entities to give them the capability
+    ///     of loading navigation properties automatically the first time they are accessed.
+    /// </summary>
+    /// <remarks>
     ///     <para>
     ///         The service lifetime is 'ServiceLifetime.Transient'. This means that each
     ///         entity instance will use its own instance of this service.
     ///         The implementation may depend on other services registered with any lifetime.
     ///         The implementation does not need to be thread-safe.
     ///     </para>
-    /// </summary>
-    /// <remarks>
-    ///     See <see href="https://aka.ms/efcore-docs-lazy-loading">Lazy loading</see> for more information.
+    ///     <para>
+    ///         See <see href="https://aka.ms/efcore-docs-lazy-loading">Lazy loading</see> for more information.
+    ///     </para>
     /// </remarks>
     public interface ILazyLoader : IDisposable
     {

src/EFCore.Cosmos/Diagnostics/CosmosEventId.cs

@@ -7,18 +7,18 @@
 namespace Microsoft.EntityFrameworkCore.Diagnostics
 {
     /// <summary>
-    ///     <para>
-    ///         Event IDs for Cosmos events that correspond to messages logged to an <see cref="ILogger" />
-    ///         and events sent to a <see cref="DiagnosticSource" />.
-    ///     </para>
+    ///     Event IDs for Cosmos events that correspond to messages logged to an <see cref="ILogger" />
+    ///     and events sent to a <see cref="DiagnosticSource" />.
+    /// </summary>
+    /// <remarks>
     ///     <para>
     ///         These IDs are also used with <see cref="WarningsConfigurationBuilder" /> to configure the
     ///         behavior of warnings.
     ///     </para>
-    /// </summary>
-    /// <remarks>
-    ///     See <see href="https://aka.ms/efcore-docs-diagnostics">Logging, events, and diagnostics</see>, and
-    ///     <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
+    ///     <para>
+    ///         See <see href="https://aka.ms/efcore-docs-diagnostics">Logging, events, and diagnostics</see>, and
+    ///         <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
+    ///     </para>
     /// </remarks>
     public static class CosmosEventId
     {
@@ -42,100 +42,100 @@ private enum Id
         private static readonly string _commandPrefix = DbLoggerCategory.Database.Command.Name + ".";
 
         /// <summary>
-        ///     <para>
-        ///         A SQL query is going to be executed.
-        ///     </para>
+        ///     A SQL query is going to be executed.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         This event is in the <see cref="DbLoggerCategory.Database.Command" /> category.
         ///     </para>
         ///     <para>
         ///         This event uses the <see cref="CosmosQueryEventData" /> payload when used with a <see cref="DiagnosticSource" />.
         ///     </para>
-        /// </summary>
+        /// </remarks>
         public static readonly EventId ExecutingSqlQuery
             = new((int)Id.ExecutingSqlQuery, _commandPrefix + Id.ExecutingSqlQuery);
 
         /// <summary>
-        ///     <para>
-        ///         ReadItem is going to be executed.
-        ///     </para>
+        ///     ReadItem is going to be executed.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         This event is in the <see cref="DbLoggerCategory.Database.Command" /> category.
         ///     </para>
         ///     <para>
         ///         This event uses the <see cref="CosmosReadItemEventData" /> payload when used with a <see cref="DiagnosticSource" />.
         ///     </para>
-        /// </summary>
+        /// </remarks>
         public static readonly EventId ExecutingReadItem
             = new((int)Id.ExecutingReadItem, _commandPrefix + Id.ExecutingReadItem);
 
         /// <summary>
-        ///     <para>
-        ///         ReadNext was executed.
-        ///     </para>
+        ///     ReadNext was executed.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         This event is in the <see cref="DbLoggerCategory.Database.Command" /> category.
         ///     </para>
         ///     <para>
         ///         This event uses the <see cref="CosmosQueryExecutedEventData" /> payload when used with a <see cref="DiagnosticSource" />.
         ///     </para>
-        /// </summary>
+        /// </remarks>
         public static readonly EventId ExecutedReadNext
             = new((int)Id.ExecutedReadNext, _commandPrefix + Id.ExecutedReadNext);
 
         /// <summary>
-        ///     <para>
-        ///         ReadItem was executed.
-        ///     </para>
+        ///     ReadItem was executed.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         This event is in the <see cref="DbLoggerCategory.Database.Command" /> category.
         ///     </para>
         ///     <para>
         ///         This event uses the <see cref="CosmosItemCommandExecutedEventData" /> payload when used with a <see cref="DiagnosticSource" />.
         ///     </para>
-        /// </summary>
+        /// </remarks>
         public static readonly EventId ExecutedReadItem
             = new((int)Id.ExecutedReadItem, _commandPrefix + Id.ExecutedReadItem);
 
         /// <summary>
-        ///     <para>
-        ///         CreateItem was executed.
-        ///     </para>
+        ///     CreateItem was executed.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         This event is in the <see cref="DbLoggerCategory.Database.Command" /> category.
         ///     </para>
         ///     <para>
         ///         This event uses the <see cref="CosmosItemCommandExecutedEventData" /> payload when used with a <see cref="DiagnosticSource" />.
         ///     </para>
-        /// </summary>
+        /// </remarks>
         public static readonly EventId ExecutedCreateItem
             = new((int)Id.ExecutedCreateItem, _commandPrefix + Id.ExecutedCreateItem);
 
         /// <summary>
-        ///     <para>
-        ///         ReplaceItem was executed.
-        ///     </para>
+        ///     ReplaceItem was executed.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         This event is in the <see cref="DbLoggerCategory.Database.Command" /> category.
         ///     </para>
         ///     <para>
         ///         This event uses the <see cref="CosmosItemCommandExecutedEventData" /> payload when used with a <see cref="DiagnosticSource" />.
         ///     </para>
-        /// </summary>
+        /// </remarks>
         public static readonly EventId ExecutedReplaceItem
             = new((int)Id.ExecutedReplaceItem, _commandPrefix + Id.ExecutedReplaceItem);
 
         /// <summary>
-        ///     <para>
-        ///         DeleteItem was executed.
-        ///     </para>
+        ///     DeleteItem was executed.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         This event is in the <see cref="DbLoggerCategory.Database.Command" /> category.
         ///     </para>
         ///     <para>
         ///         This event uses the <see cref="CosmosItemCommandExecutedEventData" /> payload when used with a <see cref="DiagnosticSource" />.
         ///     </para>
-        /// </summary>
+        /// </remarks>
         public static readonly EventId ExecutedDeleteItem
             = new((int)Id.ExecutedDeleteItem, _commandPrefix + Id.ExecutedDeleteItem);
     }

src/EFCore.Cosmos/Extensions/CosmosDatabaseFacadeExtensions.cs

@@ -44,18 +44,18 @@ private static TService GetService<TService>(IInfrastructure<IServiceProvider> d
         }
 
         /// <summary>
-        ///     <para>
-        ///         Returns <see langword="true" /> if the database provider currently in use is the Cosmos provider.
-        ///     </para>
+        ///     Returns <see langword="true" /> if the database provider currently in use is the Cosmos provider.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         This method can only be used after the <see cref="DbContext" /> has been configured because
         ///         it is only then that the provider is known. This means that this method cannot be used
         ///         in <see cref="DbContext.OnConfiguring" /> because this is where application code sets the
         ///         provider to use as part of configuring the context.
         ///     </para>
-        /// </summary>
-        /// <remarks>
-        ///     See <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
+        ///     <para>
+        ///         See <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
+        ///     </para>
         /// </remarks>
         /// <param name="database">The facade from <see cref="DbContext.Database" />.</param>
         /// <returns><see langword="true" /> if the Cosmos provider is being used.</returns>

src/EFCore.Cosmos/Extensions/CosmosPropertyBuilderExtensions.cs

@@ -21,10 +21,14 @@ public static class CosmosPropertyBuilderExtensions
         ///     Configures the property name that the property is mapped to when targeting Azure Cosmos.
         /// </summary>
         /// <remarks>
-        ///     See <see href="https://aka.ms/efcore-docs-modeling">Modeling entity types and relationships</see>, and
-        ///     <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
+        ///     <para>
+        ///         If an empty string is supplied, the property will not be persisted.
+        ///     </para>
+        ///     <para>
+        ///         See <see href="https://aka.ms/efcore-docs-modeling">Modeling entity types and relationships</see>, and
+        ///         <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
+        ///     </para>
         /// </remarks>
-        /// <remarks> If an empty string is supplied then the property will not be persisted. </remarks>
         /// <param name="propertyBuilder">The builder for the property being configured.</param>
         /// <param name="name">The name of the property.</param>
         /// <returns>The same builder instance so that multiple calls can be chained.</returns>
@@ -57,12 +61,8 @@ public static PropertyBuilder<TProperty> ToJsonProperty<TProperty>(
             => (PropertyBuilder<TProperty>)ToJsonProperty((PropertyBuilder)propertyBuilder, name);
 
         /// <summary>
-        ///     <para>
-        ///         Configures the property name that the property is mapped to when targeting Azure Cosmos.
-        ///     </para>
-        ///     <para>
-        ///         If an empty string is supplied then the property will not be persisted.
-        ///     </para>
+        ///     Configures the property name that the property is mapped to when targeting Azure Cosmos. If an empty string is
+        ///     supplied then the property will not be persisted.
         /// </summary>
         /// <remarks>
         ///     See <see href="https://aka.ms/efcore-docs-modeling">Modeling entity types and relationships</see>, and

src/EFCore.Cosmos/Extensions/CosmosQueryableExtensions.cs

@@ -58,9 +58,9 @@ source.Provider is EntityQueryProvider
         }
 
         /// <summary>
-        ///     <para>
-        ///         Creates a LINQ query based on a raw SQL query.
-        ///     </para>
+        ///     Creates a LINQ query based on a raw SQL query.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         You can compose on top of the raw SQL query using LINQ operators:
         ///     </para>
@@ -71,10 +71,10 @@ source.Provider is EntityQueryProvider
         ///         arguments. Any parameter values you supply will automatically be converted to a Cosmos parameter:
         ///     </para>
         ///     <code>context.Blogs.FromSqlRaw(""SELECT * FROM root c WHERE c["Name"] = {0})", userSuppliedSearchTerm)</code>
-        /// </summary>
-        /// <remarks>
-        ///     See <see href="https://aka.ms/efcore-docs-query">Querying data with EF Core</see>, and
-        ///     <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
+        ///     <para>
+        ///         See <see href="https://aka.ms/efcore-docs-query">Querying data with EF Core</see>, and
+        ///         <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
+        ///     </para>
         /// </remarks>
         /// <typeparam name="TEntity">The type of the elements of <paramref name="source" />.</typeparam>
         /// <param name="source">

src/EFCore.Cosmos/Extensions/CosmosServiceCollectionExtensions.cs

@@ -31,10 +31,10 @@ namespace Microsoft.Extensions.DependencyInjection
     public static class CosmosServiceCollectionExtensions
     {
         /// <summary>
-        ///     <para>
-        ///         Registers the given Entity Framework <see cref="DbContext" /> as a service in the <see cref="IServiceCollection" />
-        ///         and configures it to connect to an Azure Cosmos database.
-        ///     </para>
+        ///     Registers the given Entity Framework <see cref="DbContext" /> as a service in the <see cref="IServiceCollection" />
+        ///     and configures it to connect to an Azure Cosmos database.
+        /// </summary>
+        /// <remarks>
         ///     <para>
         ///         This method is a shortcut for configuring a <see cref="DbContext" /> to use Cosmos. It does not support all options.
         ///         Use <see cref="O:EntityFrameworkServiceCollectionExtensions.AddDbContext" /> and related methods for full control of
@@ -52,12 +52,9 @@ public static class CosmosServiceCollectionExtensions
         ///         an optional action to configure the <see cref="DbContextOptions" /> for the context.
         ///     </para>
         ///     <para>
-        ///         See <see href="https://aka.ms/efcore-docs-di">Using DbContext with dependency injection</see> for more information.
+        ///         See <see href="https://aka.ms/efcore-docs-dbcontext-options">Using DbContextOptions</see>, and
+        ///         <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
         ///     </para>
-        /// </summary>
-        /// <remarks>
-        ///     See <see href="https://aka.ms/efcore-docs-dbcontext-options">Using DbContextOptions</see>, and
-        ///     <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information.
         /// </remarks>
         /// <typeparam name="TContext">The type of context to be registered.</typeparam>
         /// <param name="serviceCollection">The <see cref="IServiceCollection" /> to add services to.</param>
@@ -79,10 +76,10 @@ public static IServiceCollection AddCosmos<TContext>(
 
             return serviceCollection.AddDbContext<TContext>(
                 (serviceProvider, options) =>
-                    {
-                        optionsAction?.Invoke(options);
-                        options.UseCosmos(connectionString, databaseName, cosmosOptionsAction);
-                    });
+                {
+                    optionsAction?.Invoke(options);
+                    options.UseCosmos(connectionString, databaseName, cosmosOptionsAction);
+                });
         }
 
         /// <summary>
@@ -94,14 +91,14 @@ public static IServiceCollection AddCosmos<TContext>(
         ///         Warning: Do not call this method accidentally. It is much more likely you need
         ///         to call <see cref="AddCosmos{TContext}" />.
         ///     </para>
-        ///     <para>
-        ///         Calling this method is no longer necessary when building most applications, including those that
-        ///         use dependency injection in ASP.NET or elsewhere.
-        ///         It is only needed when building the internal service provider for use with
-        ///         the <see cref="DbContextOptionsBuilder.UseInternalServiceProvider" /> method.
-        ///         This is not recommend other than for some advanced scenarios.
-        ///     </para>
         /// </summary>
+        /// <remarks>
+        ///     Calling this method is no longer necessary when building most applications, including those that
+        ///     use dependency injection in ASP.NET or elsewhere.
+        ///     It is only needed when building the internal service provider for use with
+        ///     the <see cref="DbContextOptionsBuilder.UseInternalServiceProvider" /> method.
+        ///     This is not recommend other than for some advanced scenarios.
+        /// </remarks>
         /// <param name="serviceCollection">The <see cref="IServiceCollection" /> to add services to.</param>
         /// <returns>
         ///     The same service collection so that multiple calls can be chained.