More doc updates for source-of-truth assemblies (dotnet#107965)

tomeksowi · Sep 23, 2024 · 60d31e7 · 60d31e7
1 parent 0f9caba
commit 60d31e7
Show file tree

Hide file tree

Showing 30 changed files with 256 additions and 220 deletions.
diff --git a/...osoft.Extensions.Options.ConfigurationExtensions/src/ConfigureFromConfigurationOptions.cs b/...osoft.Extensions.Options.ConfigurationExtensions/src/ConfigureFromConfigurationOptions.cs
@@ -18,7 +18,7 @@ public class ConfigureFromConfigurationOptions<[DynamicallyAccessedMembers(Dynam
         where TOptions : class
     {
         /// <summary>
-        /// Constructor that takes the <see cref="IConfiguration"/> instance to bind against.
+        /// Initializes a new instance of the <see cref="ConfigureFromConfigurationOptions{TOptions}"/> class using the specified <see cref="IConfiguration"/> instance to bind against.
         /// </summary>
         /// <param name="config">The <see cref="IConfiguration"/> instance.</param>
         //Even though TOptions is annotated, we need to annotate as RUC as we can't guarantee properties on referenced types are preserved.

diff --git a/...braries/Microsoft.Extensions.Options.DataAnnotations/src/DataAnnotationValidateOptions.cs b/...braries/Microsoft.Extensions.Options.DataAnnotations/src/DataAnnotationValidateOptions.cs
@@ -20,7 +20,7 @@ public class DataAnnotationValidateOptions<[DynamicallyAccessedMembers(Dynamical
         : IValidateOptions<TOptions> where TOptions : class
     {
         /// <summary>
-        /// Constructor.
+        /// Initializes a new instance of <see cref="DataAnnotationValidateOptions{TOptions}"/> .
         /// </summary>
         /// <param name="name">The name of the option.</param>
         [RequiresUnreferencedCode("The implementation of Validate method on this type will walk through all properties of the passed in options object, and its type cannot be " +
@@ -31,7 +31,7 @@ public DataAnnotationValidateOptions(string? name)
         }
 
         /// <summary>
-        /// The options name.
+        /// Gets the options name.
         /// </summary>
         public string? Name { get; }
 

diff --git a/src/libraries/Microsoft.Extensions.Options/src/ConfigureNamedOptions.cs b/src/libraries/Microsoft.Extensions.Options/src/ConfigureNamedOptions.cs
@@ -12,7 +12,7 @@ namespace Microsoft.Extensions.Options
     public class ConfigureNamedOptions<TOptions> : IConfigureNamedOptions<TOptions> where TOptions : class
     {
         /// <summary>
-        /// Constructor.
+        /// Initializes a new instance of <see cref="ConfigureNamedOptions{TOptions}"/>.
         /// </summary>
         /// <param name="name">The name of the options.</param>
         /// <param name="action">The action to register.</param>
@@ -23,12 +23,12 @@ public ConfigureNamedOptions(string? name, Action<TOptions>? action)
         }
 
         /// <summary>
-        /// The options name.
+        /// Gets the options name.
         /// </summary>
         public string? Name { get; }
 
         /// <summary>
-        /// The configuration action.
+        /// Gets the configuration action.
         /// </summary>
         public Action<TOptions>? Action { get; }
 
@@ -49,7 +49,7 @@ public virtual void Configure(string? name, TOptions options)
         }
 
         /// <summary>
-        /// Invoked to configure a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
+        /// Configures a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
         /// </summary>
         /// <param name="options">The options instance to configure.</param>
         public void Configure(TOptions options) => Configure(Options.DefaultName, options);
@@ -65,7 +65,7 @@ public class ConfigureNamedOptions<TOptions, TDep> : IConfigureNamedOptions<TOpt
         where TDep : class
     {
         /// <summary>
-        /// Constructor.
+        /// Initializes a new instance of <see cref="ConfigureNamedOptions{TOptions, TDep}"/>.
         /// </summary>
         /// <param name="name">The name of the options.</param>
         /// <param name="dependency">A dependency.</param>
@@ -78,17 +78,17 @@ public ConfigureNamedOptions(string? name, TDep dependency, Action<TOptions, TDe
         }
 
         /// <summary>
-        /// The options name.
+        /// Gets the options name.
         /// </summary>
         public string? Name { get; }
 
         /// <summary>
-        /// The configuration action.
+        /// Gets the configuration action.
         /// </summary>
         public Action<TOptions, TDep>? Action { get; }
 
         /// <summary>
-        /// The dependency.
+        /// Gets the dependency.
         /// </summary>
         public TDep Dependency { get; }
 
@@ -109,7 +109,7 @@ public virtual void Configure(string? name, TOptions options)
         }
 
         /// <summary>
-        /// Invoked to configure a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
+        /// Configures a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
         /// </summary>
         /// <param name="options">The options instance to configure.</param>
         public void Configure(TOptions options) => Configure(Options.DefaultName, options);
@@ -127,7 +127,7 @@ public class ConfigureNamedOptions<TOptions, TDep1, TDep2> : IConfigureNamedOpti
         where TDep2 : class
     {
         /// <summary>
-        /// Constructor.
+        /// Initializes a new instance of <see cref="ConfigureNamedOptions{TOptions, TDep1, TDep2}"/>.
         /// </summary>
         /// <param name="name">The name of the options.</param>
         /// <param name="dependency">A dependency.</param>
@@ -142,22 +142,22 @@ public ConfigureNamedOptions(string? name, TDep1 dependency, TDep2 dependency2,
         }
 
         /// <summary>
-        /// The options name.
+        /// Gets the options name.
         /// </summary>
         public string? Name { get; }
 
         /// <summary>
-        /// The configuration action.
+        /// Gets the configuration action.
         /// </summary>
         public Action<TOptions, TDep1, TDep2>? Action { get; }
 
         /// <summary>
-        /// The first dependency.
+        /// Gets the first dependency.
         /// </summary>
         public TDep1 Dependency1 { get; }
 
         /// <summary>
-        /// The second dependency.
+        /// Gets the second dependency.
         /// </summary>
         public TDep2 Dependency2 { get; }
 
@@ -178,7 +178,7 @@ public virtual void Configure(string? name, TOptions options)
         }
 
         /// <summary>
-        /// Invoked to configure a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
+        /// Configures a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
         /// </summary>
         /// <param name="options">The options instance to configure.</param>
         public void Configure(TOptions options) => Configure(Options.DefaultName, options);
@@ -215,27 +215,27 @@ public ConfigureNamedOptions(string? name, TDep1 dependency, TDep2 dependency2,
         }
 
         /// <summary>
-        /// The options name.
+        /// Gets the options name.
         /// </summary>
         public string? Name { get; }
 
         /// <summary>
-        /// The configuration action.
+        /// Gets the configuration action.
         /// </summary>
         public Action<TOptions, TDep1, TDep2, TDep3>? Action { get; }
 
         /// <summary>
-        /// The first dependency.
+        /// Gets the first dependency.
         /// </summary>
         public TDep1 Dependency1 { get; }
 
         /// <summary>
-        /// The second dependency.
+        /// Gets the second dependency.
         /// </summary>
         public TDep2 Dependency2 { get; }
 
         /// <summary>
-        /// The third dependency.
+        /// Gets the third dependency.
         /// </summary>
         public TDep3 Dependency3 { get; }
 
@@ -256,7 +256,7 @@ public virtual void Configure(string? name, TOptions options)
         }
 
         /// <summary>
-        /// Invoked to configure a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
+        /// Configures a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
         /// </summary>
         /// <param name="options">The options instance to configure.</param>
         public void Configure(TOptions options) => Configure(Options.DefaultName, options);
@@ -297,32 +297,32 @@ public ConfigureNamedOptions(string? name, TDep1 dependency1, TDep2 dependency2,
         }
 
         /// <summary>
-        /// The options name.
+        /// Gets the options name.
         /// </summary>
         public string? Name { get; }
 
         /// <summary>
-        /// The configuration action.
+        /// Gets the configuration action.
         /// </summary>
         public Action<TOptions, TDep1, TDep2, TDep3, TDep4>? Action { get; }
 
         /// <summary>
-        /// The first dependency.
+        /// Gets the first dependency.
         /// </summary>
         public TDep1 Dependency1 { get; }
 
         /// <summary>
-        /// The second dependency.
+        /// Gets the second dependency.
         /// </summary>
         public TDep2 Dependency2 { get; }
 
         /// <summary>
-        /// The third dependency.
+        /// Gets the third dependency.
         /// </summary>
         public TDep3 Dependency3 { get; }
 
         /// <summary>
-        /// The fourth dependency.
+        /// Gets the fourth dependency.
         /// </summary>
         public TDep4 Dependency4 { get; }
 
@@ -343,7 +343,7 @@ public virtual void Configure(string? name, TOptions options)
         }
 
         /// <summary>
-        /// Invoked to configure a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
+        /// Configures a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
         /// </summary>
         /// <param name="options">The options instance to configure.</param>
         public void Configure(TOptions options) => Configure(Options.DefaultName, options);
@@ -388,37 +388,37 @@ public ConfigureNamedOptions(string? name, TDep1 dependency1, TDep2 dependency2,
         }
 
         /// <summary>
-        /// The options name.
+        /// Gets the options name.
         /// </summary>
         public string? Name { get; }
 
         /// <summary>
-        /// The configuration action.
+        /// Gets the configuration action.
         /// </summary>
         public Action<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5>? Action { get; }
 
         /// <summary>
-        /// The first dependency.
+        /// Gets the first dependency.
         /// </summary>
         public TDep1 Dependency1 { get; }
 
         /// <summary>
-        /// The second dependency.
+        /// Gets the second dependency.
         /// </summary>
         public TDep2 Dependency2 { get; }
 
         /// <summary>
-        /// The third dependency.
+        /// Gets the third dependency.
         /// </summary>
         public TDep3 Dependency3 { get; }
 
         /// <summary>
-        /// The fourth dependency.
+        /// Gets the fourth dependency.
         /// </summary>
         public TDep4 Dependency4 { get; }
 
         /// <summary>
-        /// The fifth dependency.
+        /// Gets the fifth dependency.
         /// </summary>
         public TDep5 Dependency5 { get; }
 
@@ -439,7 +439,7 @@ public virtual void Configure(string? name, TOptions options)
         }
 
         /// <summary>
-        /// Invoked to configure a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
+        /// Configures a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
         /// </summary>
         /// <param name="options">The options instance to configure.</param>
         public void Configure(TOptions options) => Configure(Options.DefaultName, options);

diff --git a/src/libraries/Microsoft.Extensions.Options/src/ConfigureOptions.cs b/src/libraries/Microsoft.Extensions.Options/src/ConfigureOptions.cs
@@ -12,7 +12,7 @@ namespace Microsoft.Extensions.Options
     public class ConfigureOptions<TOptions> : IConfigureOptions<TOptions> where TOptions : class
     {
         /// <summary>
-        /// Constructor.
+        /// Initializes a new instance of <see cref="ConfigureOptions{TOptions}"/>.
         /// </summary>
         /// <param name="action">The action to register.</param>
         public ConfigureOptions(Action<TOptions>? action)
@@ -21,7 +21,7 @@ public ConfigureOptions(Action<TOptions>? action)
         }
 
         /// <summary>
-        /// The configuration action.
+        /// Gets the configuration action.
         /// </summary>
         public Action<TOptions>? Action { get; }
 

diff --git a/src/libraries/Microsoft.Extensions.Options/src/IConfigureNamedOptions.cs b/src/libraries/Microsoft.Extensions.Options/src/IConfigureNamedOptions.cs
@@ -10,7 +10,7 @@ namespace Microsoft.Extensions.Options
     public interface IConfigureNamedOptions<in TOptions> : IConfigureOptions<TOptions> where TOptions : class
     {
         /// <summary>
-        /// Invoked to configure a <typeparamref name="TOptions"/> instance.
+        /// Configures a <typeparamref name="TOptions"/> instance.
         /// </summary>
         /// <param name="name">The name of the options instance being configured.</param>
         /// <param name="options">The options instance to configure.</param>

diff --git a/src/libraries/Microsoft.Extensions.Options/src/IConfigureOptions.cs b/src/libraries/Microsoft.Extensions.Options/src/IConfigureOptions.cs
@@ -5,13 +5,15 @@ namespace Microsoft.Extensions.Options
 {
     /// <summary>
     /// Represents something that configures the <typeparamref name="TOptions"/> type.
-    /// Note: These are run before all <see cref="IPostConfigureOptions{TOptions}"/>.
     /// </summary>
     /// <typeparam name="TOptions">The options type being configured.</typeparam>
+    /// <remarks>
+    /// These are run before all <see cref="IPostConfigureOptions{TOptions}"/>.
+    /// </remarks>
     public interface IConfigureOptions<in TOptions> where TOptions : class
     {
         /// <summary>
-        /// Invoked to configure a <typeparamref name="TOptions"/> instance.
+        /// Configures a <typeparamref name="TOptions"/> instance.
         /// </summary>
         /// <param name="options">The options instance to configure.</param>
         void Configure(TOptions options);

diff --git a/src/libraries/Microsoft.Extensions.Options/src/IOptions.cs b/src/libraries/Microsoft.Extensions.Options/src/IOptions.cs
@@ -6,14 +6,14 @@
 namespace Microsoft.Extensions.Options
 {
     /// <summary>
-    /// Used to retrieve configured <typeparamref name="TOptions"/> instances.
+    /// Retrieves configured <typeparamref name="TOptions"/> instances.
     /// </summary>
     /// <typeparam name="TOptions">The type of options being requested.</typeparam>
     public interface IOptions<[DynamicallyAccessedMembers(Options.DynamicallyAccessedMembers)] out TOptions>
         where TOptions : class
     {
         /// <summary>
-        /// The default configured <typeparamref name="TOptions"/> instance
+        /// Gets the default configured <typeparamref name="TOptions"/> instance.
         /// </summary>
         TOptions Value { get; }
     }

diff --git a/src/libraries/Microsoft.Extensions.Options/src/IOptionsChangeTokenSource.cs b/src/libraries/Microsoft.Extensions.Options/src/IOptionsChangeTokenSource.cs
@@ -6,19 +6,19 @@
 namespace Microsoft.Extensions.Options
 {
     /// <summary>
-    /// Used to fetch <see cref="IChangeToken"/> used for tracking options changes.
+    /// Fetches a <see cref="IChangeToken"/> that's used for tracking options changes.
     /// </summary>
     /// <typeparam name="TOptions">The options type being changed.</typeparam>
     public interface IOptionsChangeTokenSource<out TOptions>
     {
         /// <summary>
-        /// Returns a <see cref="IChangeToken"/> which can be used to register a change notification callback.
+        /// Returns a <see cref="IChangeToken"/> that can be used to register a change notification callback.
         /// </summary>
-        /// <returns>Change token.</returns>
+        /// <returns>A change token.</returns>
         IChangeToken GetChangeToken();
 
         /// <summary>
-        /// The name of the option instance being changed.
+        /// Gets the name of the option instance being changed.
         /// </summary>
         string? Name { get; }
     }

diff --git a/src/libraries/Microsoft.Extensions.Options/src/IOptionsFactory.cs b/src/libraries/Microsoft.Extensions.Options/src/IOptionsFactory.cs
@@ -7,7 +7,7 @@
 namespace Microsoft.Extensions.Options
 {
     /// <summary>
-    /// Used to create <typeparamref name="TOptions"/> instances.
+    /// Creates <typeparamref name="TOptions"/> instances.
     /// </summary>
     /// <typeparam name="TOptions">The type of options being requested.</typeparam>
     public interface IOptionsFactory<[DynamicallyAccessedMembers(Options.DynamicallyAccessedMembers)] TOptions>

diff --git a/src/libraries/Microsoft.Extensions.Options/src/IOptionsMonitor.cs b/src/libraries/Microsoft.Extensions.Options/src/IOptionsMonitor.cs
@@ -7,13 +7,13 @@
 namespace Microsoft.Extensions.Options
 {
     /// <summary>
-    /// Used for notifications when <typeparamref name="TOptions"/> instances change.
+    /// Monitors changes on a <typeparamref name="TOptions"/> instance.
     /// </summary>
     /// <typeparam name="TOptions">The options type.</typeparam>
     public interface IOptionsMonitor<[DynamicallyAccessedMembers(Options.DynamicallyAccessedMembers)] out TOptions>
     {
         /// <summary>
-        /// Returns the current <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
+        /// Gets the current <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>.
         /// </summary>
         TOptions CurrentValue { get; }