Skip to content

Commit 48fa780

Browse files
gewarrengewarren
authored
Doc updates (#64092)
1 parent c66fabe commit 48fa780

File tree

13 files changed

+110
-70
lines changed

13 files changed

+110
-70
lines changed

‎src/Caching/SqlServer/src/SqlServerCacheOptions.cs‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,39 +8,44 @@
88
namespace Microsoft.Extensions.Caching.SqlServer;
99

1010
/// <summary>
11-
/// Configuration options for <see cref="SqlServerCache"/>.
11+
/// Represents configuration options for <see cref="SqlServerCache"/>.
1212
/// </summary>
1313
public class SqlServerCacheOptions : IOptions<SqlServerCacheOptions>
1414
{
1515
/// <summary>
16-
/// An abstraction to represent the clock of a machine in order to enable unit testing.
16+
/// Gets or sets an abstraction to represent the clock of a machine in order to enable unit testing.
1717
/// </summary>
1818
public ISystemClock SystemClock { get; set; } = new SystemClock();
1919

2020
/// <summary>
21-
/// The periodic interval to scan and delete expired items in the cache. Default is 30 minutes.
21+
/// Gets or sets the periodic interval to scan and delete expired items in the cache. Default is 30 minutes.
2222
/// </summary>
23+
/// <value>
24+
/// The periodic interval to scan and delete expired items in the cache. The default is 30 minutes.
25+
/// </value>
2326
public TimeSpan? ExpiredItemsDeletionInterval { get; set; }
2427

2528
/// <summary>
26-
/// The connection string to the database.
29+
/// Gets or sets the connection string to the database.
2730
/// </summary>
2831
public string? ConnectionString { get; set; }
2932

3033
/// <summary>
31-
/// The schema name of the table.
34+
/// Gets or sets the schema name of the table.
3235
/// </summary>
3336
public string? SchemaName { get; set; }
3437

3538
/// <summary>
36-
/// Name of the table where the cache items are stored.
39+
/// Gets or sets the name of the table where the cache items are stored.
3740
/// </summary>
3841
public string? TableName { get; set; }
3942

4043
/// <summary>
41-
/// The default sliding expiration set for a cache entry if neither Absolute or SlidingExpiration has been set explicitly.
42-
/// By default, its 20 minutes.
44+
/// Gets or sets the default sliding expiration set for a cache entry if neither Absolute or SlidingExpiration has been set explicitly.
4345
/// </summary>
46+
/// <value>
47+
/// The default is 20 minutes.
48+
/// </value>
4449
public TimeSpan DefaultSlidingExpiration { get; set; } = TimeSpan.FromMinutes(20);
4550

4651
SqlServerCacheOptions IOptions<SqlServerCacheOptions>.Value

‎src/HttpClientFactory/Polly/src/DependencyInjection/PollyHttpClientBuilderExtensions.cs‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,13 @@
1111
namespace Microsoft.Extensions.DependencyInjection;
1212

1313
/// <summary>
14-
/// Extensions methods for configuring <see cref="PolicyHttpMessageHandler"/> message handlers as part of
14+
/// Provides extensions methods for configuring <see cref="PolicyHttpMessageHandler"/> message handlers as part of
1515
/// and <see cref="HttpClient"/> message handler pipeline.
1616
/// </summary>
1717
public static class PollyHttpClientBuilderExtensions
1818
{
1919
/// <summary>
20-
/// Adds a <see cref="PolicyHttpMessageHandler"/> which will surround request execution with the provided
20+
/// Adds a <see cref="PolicyHttpMessageHandler"/> that will surround request execution with the provided
2121
/// <see cref="IAsyncPolicy{HttpResponseMessage}"/>.
2222
/// </summary>
2323
/// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
@@ -45,7 +45,7 @@ public static IHttpClientBuilder AddPolicyHandler(this IHttpClientBuilder builde
4545
}
4646

4747
/// <summary>
48-
/// Adds a <see cref="PolicyHttpMessageHandler"/> which will surround request execution with a policy returned
48+
/// Adds a <see cref="PolicyHttpMessageHandler"/> that will surround request execution with a policy returned
4949
/// by the <paramref name="policySelector"/>.
5050
/// </summary>
5151
/// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
@@ -77,7 +77,7 @@ public static IHttpClientBuilder AddPolicyHandler(
7777
}
7878

7979
/// <summary>
80-
/// Adds a <see cref="PolicyHttpMessageHandler"/> which will surround request execution with a policy returned
80+
/// Adds a <see cref="PolicyHttpMessageHandler"/> that will surround request execution with a policy returned
8181
/// by the <paramref name="policySelector"/>.
8282
/// </summary>
8383
/// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
@@ -112,7 +112,7 @@ public static IHttpClientBuilder AddPolicyHandler(
112112
}
113113

114114
/// <summary>
115-
/// Adds a <see cref="PolicyHttpMessageHandler"/> which will surround request execution with a policy returned
115+
/// Adds a <see cref="PolicyHttpMessageHandler"/> that will surround request execution with a policy returned
116116
/// by the <see cref="IReadOnlyPolicyRegistry{String}"/>.
117117
/// </summary>
118118
/// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
@@ -149,7 +149,7 @@ public static IHttpClientBuilder AddPolicyHandlerFromRegistry(this IHttpClientBu
149149
}
150150

151151
/// <summary>
152-
/// Adds a <see cref="PolicyHttpMessageHandler"/> which will surround request execution with a policy returned
152+
/// Adds a <see cref="PolicyHttpMessageHandler"/> that will surround request execution with a policy returned
153153
/// by the <see cref="IReadOnlyPolicyRegistry{String}"/>.
154154
/// </summary>
155155
/// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
@@ -185,7 +185,7 @@ public static IHttpClientBuilder AddPolicyHandlerFromRegistry(
185185
}
186186

187187
/// <summary>
188-
/// Adds a <see cref="PolicyHttpMessageHandler"/> which will surround request execution with a <see cref="Policy"/>
188+
/// Adds a <see cref="PolicyHttpMessageHandler"/> that will surround request execution with a <see cref="Policy"/>
189189
/// created by executing the provided configuration delegate. The policy builder will be preconfigured to trigger
190190
/// application of the policy for requests that fail with conditions that indicate a transient failure.
191191
/// </summary>
@@ -207,8 +207,8 @@ public static IHttpClientBuilder AddPolicyHandlerFromRegistry(
207207
/// </para>
208208
/// <para>
209209
/// The policy created by <paramref name="configurePolicy"/> will be cached indefinitely per named client. Policies
210-
/// are generally designed to act as singletons, and can be shared when appropriate. To share a policy across multiple
211-
/// named clients, first create the policy and then pass it to multiple calls to
210+
/// are generally designed to act as singletons and can be shared when appropriate. To share a policy across multiple
211+
/// named clients, first create the policy and then pass it to multiple calls to
212212
/// <see cref="AddPolicyHandler(IHttpClientBuilder, IAsyncPolicy{HttpResponseMessage})"/> as desired.
213213
/// </para>
214214
/// </remarks>
@@ -236,8 +236,8 @@ public static IHttpClientBuilder AddTransientHttpErrorPolicy(
236236
}
237237

238238
/// <summary>
239-
/// Adds a <see cref="PolicyHttpMessageHandler"/> which will surround request execution with a policy returned
240-
/// by executing provided key selection logic <paramref name="keySelector"/> and <paramref name="policyFactory"/>
239+
/// Adds a <see cref="PolicyHttpMessageHandler"/> that will surround request execution with a policy returned
240+
/// by executing provided key selection logic <paramref name="keySelector"/> and <paramref name="policyFactory"/>.
241241
/// </summary>
242242
/// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
243243
/// <param name="policyFactory">Selects an <see cref="IAsyncPolicy{HttpResponseMessage}"/> to apply to the current request based on key selection.</param>

‎src/Logging.AzureAppServices/src/AzureAppServicesLoggerFactoryExtensions.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,14 @@
1313
namespace Microsoft.Extensions.Logging;
1414

1515
/// <summary>
16-
/// Extension methods for adding Azure diagnostics logger.
16+
/// Provides extension methods for adding Azure diagnostics logger.
1717
/// </summary>
1818
public static class AzureAppServicesLoggerFactoryExtensions
1919
{
2020
/// <summary>
2121
/// Adds an Azure Web Apps diagnostics logger.
2222
/// </summary>
23-
/// <param name="builder">The extension method argument</param>
23+
/// <param name="builder">The extension method argument.</param>
2424
/// <returns></returns>
2525
public static ILoggingBuilder AddAzureWebAppDiagnostics(this ILoggingBuilder builder)
2626
{

‎src/Logging.AzureAppServices/src/AzureBlobLoggerContext.cs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@
66
namespace Microsoft.Extensions.Logging.AzureAppServices;
77

88
/// <summary>
9-
/// The context containing details for formatting the file name for the azure blob logger.
9+
/// Represents the context containing details for formatting the file name for the Azure blob logger.
1010
/// </summary>
1111
public readonly struct AzureBlobLoggerContext
1212
{
1313
/// <summary>
14-
/// Create a new <see cref="AzureBlobLoggerContext"/>.
14+
/// Creates a new <see cref="AzureBlobLoggerContext"/>.
1515
/// </summary>
1616
/// <param name="appName">The app name.</param>
1717
/// <param name="identifier">The file identifier.</param>
@@ -24,17 +24,17 @@ public AzureBlobLoggerContext(string appName, string identifier, DateTimeOffset
2424
}
2525

2626
/// <summary>
27-
/// The name of the application.
27+
/// Gets the name of the application.
2828
/// </summary>
2929
public string AppName { get; }
3030

3131
/// <summary>
32-
/// The identifier for the log. This value is set to "<see cref="AzureBlobLoggerOptions.ApplicationInstanceId"/>_<see cref="AzureBlobLoggerOptions.BlobName"/>".
32+
/// Gets the identifier for the log. This value is set to "<see cref="AzureBlobLoggerOptions.ApplicationInstanceId"/>_<see cref="AzureBlobLoggerOptions.BlobName"/>".
3333
/// </summary>
3434
public string Identifier { get; }
3535

3636
/// <summary>
37-
/// The timestamp representing when the log was created.
37+
/// Gets the timestamp representing when the log was created.
3838
/// </summary>
3939
public DateTimeOffset Timestamp { get; }
4040
}

‎src/Logging.AzureAppServices/src/AzureBlobLoggerOptions.cs‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,18 @@
77
namespace Microsoft.Extensions.Logging.AzureAppServices;
88

99
/// <summary>
10-
/// Options for Azure diagnostics blob logging.
10+
/// Specifies options for Azure diagnostics blob logging.
1111
/// </summary>
1212
public class AzureBlobLoggerOptions : BatchingLoggerOptions
1313
{
1414
private string _blobName = "applicationLog.txt";
1515

1616
/// <summary>
1717
/// Gets or sets the last section of log blob name.
18-
/// Defaults to <c>"applicationLog.txt"</c>.
1918
/// </summary>
19+
/// <value>
20+
/// The last section of the log blob name. The default is <c>"applicationLog.txt"</c>.
21+
/// </value>
2022
public string BlobName
2123
{
2224
get { return _blobName; }
@@ -29,8 +31,10 @@ public string BlobName
2931

3032
/// <summary>
3133
/// Gets or sets the format of the file name.
32-
/// Defaults to "AppName/Year/Month/Day/Hour/Identifier".
3334
/// </summary>
35+
/// <value>
36+
/// The format of the file name. The default is "AppName/Year/Month/Day/Hour/Identifier".
37+
/// </value>
3438
public Func<AzureBlobLoggerContext, string> FileNameFormat { get; set; } = context =>
3539
{
3640
var timestamp = context.Timestamp;

‎src/Logging.AzureAppServices/src/AzureFileLoggerOptions.cs‎

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
namespace Microsoft.Extensions.Logging.AzureAppServices;
88

99
/// <summary>
10-
/// Options for Azure diagnostics file logging.
10+
/// Specifies options for Azure diagnostics file logging.
1111
/// </summary>
1212
public class AzureFileLoggerOptions : BatchingLoggerOptions
1313
{
@@ -16,10 +16,15 @@ public class AzureFileLoggerOptions : BatchingLoggerOptions
1616
private string _fileName = "diagnostics-";
1717

1818
/// <summary>
19-
/// Gets or sets a strictly positive value representing the maximum log size in bytes or null for no limit.
20-
/// Once the log is full, no more messages will be appended.
21-
/// Defaults to <c>10MB</c>.
19+
/// Gets or sets a strictly positive value representing the maximum log size in bytes, or null for no limit.
2220
/// </summary>
21+
/// <value>
22+
/// The maximum log size in bytes, or <see langword="null" /> for no limit.
23+
/// The default is 10 MB.
24+
/// </value>
25+
/// <remarks>
26+
/// Once the log is full, no more messages are appended.
27+
/// </remarks>
2328
public int? FileSizeLimit
2429
{
2530
get { return _fileSizeLimit; }
@@ -34,9 +39,12 @@ public int? FileSizeLimit
3439
}
3540

3641
/// <summary>
37-
/// Gets or sets a strictly positive value representing the maximum retained file count or null for no limit.
38-
/// Defaults to <c>2</c>.
42+
/// Gets or sets a strictly positive value representing the maximum retained file count.
3943
/// </summary>
44+
/// <value>
45+
/// The maximum retained file count, or <see langword="null" /> for no limit.
46+
/// The default is 2.
47+
/// </value>
4048
public int? RetainedFileCountLimit
4149
{
4250
get { return _retainedFileCountLimit; }
@@ -51,10 +59,13 @@ public int? RetainedFileCountLimit
5159
}
5260

5361
/// <summary>
54-
/// Gets or sets a string representing the prefix of the file name used to store the logging information.
55-
/// The current date, in the format YYYYMMDD will be added after the given value.
56-
/// Defaults to <c>diagnostics-</c>.
62+
/// Gets or sets the prefix of the file name used to store the logging information.
63+
/// The current date, in the format YYYYMMDD, is added after this value.
5764
/// </summary>
65+
/// <value>
66+
/// The prefix of the file name used to store the logging information.
67+
/// The default is <c>diagnostics-</c>.
68+
/// </value>
5869
public string FileName
5970
{
6071
get { return _fileName; }

‎src/Logging.AzureAppServices/src/BatchingLoggerOptions.cs‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
namespace Microsoft.Extensions.Logging.AzureAppServices;
77

88
/// <summary>
9-
/// Options for a logger which batches up log messages.
9+
/// Specifies options for a logger that batches log messages.
1010
/// </summary>
1111
public class BatchingLoggerOptions
1212
{
@@ -31,10 +31,14 @@ public TimeSpan FlushPeriod
3131
}
3232

3333
/// <summary>
34-
/// Gets or sets the maximum size of the background log message queue or null for no limit.
35-
/// After maximum queue size is reached log event sink would start blocking.
36-
/// Defaults to <c>1000</c>.
34+
/// Gets or sets the maximum size of the background log message queue, or null for no limit.
3735
/// </summary>
36+
/// <value>
37+
/// The maximum size of the background log message queue, or <see langword="null" /> for no limit. The default is 1000.
38+
/// </value>
39+
/// <remarks>
40+
/// After the maximum queue size is reached, the log event sink starts blocking.
41+
/// </remarks>
3842
public int? BackgroundQueueSize
3943
{
4044
get { return _backgroundQueueSize; }
@@ -49,9 +53,11 @@ public int? BackgroundQueueSize
4953
}
5054

5155
/// <summary>
52-
/// Gets or sets a maximum number of events to include in a single batch or null for no limit.
56+
/// Gets or sets the maximum number of events to include in a single batch.
5357
/// </summary>
54-
/// Defaults to <c>null</c>.
58+
/// <value>
59+
/// The maximum number of events to include in a single batch, or <see langword="null" /> for no limit. The default is <see langword="null" />.
60+
/// </value>
5561
public int? BatchSize
5662
{
5763
get { return _batchSize; }
@@ -66,13 +72,15 @@ public int? BatchSize
6672
}
6773

6874
/// <summary>
69-
/// Gets or sets value indicating if logger accepts and queues writes.
75+
/// Gets or sets a value indicating whether the logger accepts and queues writes.
7076
/// </summary>
7177
public bool IsEnabled { get; set; }
7278

7379
/// <summary>
7480
/// Gets or sets a value indicating whether scopes should be included in the message.
75-
/// Defaults to <c>false</c>.
7681
/// </summary>
82+
/// <value>
83+
/// The default is <see langword="false" />.
84+
/// </value>
7785
public bool IncludeScopes { get; set; }
7886
}

‎src/Logging.AzureAppServices/src/BatchingLoggerProvider.cs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
namespace Microsoft.Extensions.Logging.AzureAppServices;
1212

1313
/// <summary>
14-
/// A provider of <see cref="BatchingLogger"/> instances.
14+
/// Represents a provider of <see cref="BatchingLogger"/> instances.
1515
/// </summary>
1616
public abstract class BatchingLoggerProvider : ILoggerProvider, ISupportExternalScope
1717
{
@@ -59,7 +59,7 @@ internal BatchingLoggerProvider(IOptionsMonitor<BatchingLoggerOptions> options)
5959
}
6060

6161
/// <summary>
62-
/// Checks if the queue is enabled.
62+
/// Gets a value that indicates whether the queue is enabled.
6363
/// </summary>
6464
public bool IsEnabled { get; private set; }
6565

@@ -124,11 +124,11 @@ private async Task ProcessLogQueue()
124124
}
125125

126126
/// <summary>
127-
/// Wait for the given <see cref="TimeSpan"/>.
127+
/// Waits for the given <see cref="TimeSpan"/>.
128128
/// </summary>
129129
/// <param name="interval">The amount of time to wait.</param>
130130
/// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the delay.</param>
131-
/// <returns>A <see cref="Task"/> which completes when the <paramref name="interval"/> has passed or the <paramref name="cancellationToken"/> has been canceled.</returns>
131+
/// <returns>A <see cref="Task"/> that completes when the <paramref name="interval"/> has passed or the <paramref name="cancellationToken"/> has been canceled.</returns>
132132
protected virtual Task IntervalAsync(TimeSpan interval, CancellationToken cancellationToken)
133133
{
134134
return Task.Delay(interval, cancellationToken);

‎src/Logging.AzureAppServices/src/FileLoggerProvider.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
namespace Microsoft.Extensions.Logging.AzureAppServices;
1313

1414
/// <summary>
15-
/// A <see cref="BatchingLoggerProvider"/> which writes out to a file.
15+
/// Represents a <see cref="BatchingLoggerProvider"/> that writes out to a file.
1616
/// </summary>
1717
[ProviderAlias("AzureAppServicesFile")]
1818
public class FileLoggerProvider : BatchingLoggerProvider
@@ -25,7 +25,7 @@ public class FileLoggerProvider : BatchingLoggerProvider
2525
/// <summary>
2626
/// Creates a new instance of <see cref="FileLoggerProvider"/>.
2727
/// </summary>
28-
/// <param name="options">The options to use when creating a provider.</param>
28+
/// <param name="options">The options to use when creating the provider.</param>
2929
[SuppressMessage("ApiDesign", "RS0022:Constructor make noninheritable base class inheritable", Justification = "Required for backwards compatibility")]
3030
public FileLoggerProvider(IOptionsMonitor<AzureFileLoggerOptions> options) : base(options)
3131
{

0 commit comments

Comments
 (0)