Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use remarks in XML docs #26439

Merged
merged 3 commits into from
Oct 23, 2021
Merged

Use remarks in XML docs #26439

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
453c0cc
Use remarks in XML docs
ajcvickers Oct 19, 2021
2fbda5d
Update src/EFCore.Cosmos/Extensions/CosmosPropertyBuilderExtensions.cs
ajcvickers Oct 23, 2021
0b74db9
Revert generated code change.
ajcvickers Oct 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
12 changes: 6 additions & 6 deletions src/EFCore.Abstractions/ChangeTracking/ObservableCollectionListSource.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
14 changes: 7 additions & 7 deletions src/EFCore.Abstractions/Infrastructure/ILazyLoader.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down
1 change: 0 additions & 1 deletion src/EFCore.Abstractions/Properties/AbstractionsStrings.Designer.cs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

72 changes: 36 additions & 36 deletions src/EFCore.Cosmos/Diagnostics/CosmosEventId.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand All @@ -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);
}
Expand Down
12 changes: 6 additions & 6 deletions src/EFCore.Cosmos/Extensions/CosmosDatabaseFacadeExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
18 changes: 9 additions & 9 deletions src/EFCore.Cosmos/Extensions/CosmosPropertyBuilderExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand Down
14 changes: 7 additions & 7 deletions src/EFCore.Cosmos/Extensions/CosmosQueryableExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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">
Expand Down
37 changes: 17 additions & 20 deletions src/EFCore.Cosmos/Extensions/CosmosServiceCollectionExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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.
Expand Down
Loading