More doc updates for source-of-truth assemblies (#107810) (#108257)

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>

src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Metrics/IMetricsBuilder.cs

@@ -6,13 +6,13 @@
 namespace Microsoft.Extensions.Diagnostics.Metrics
 {
     /// <summary>
-    /// Represents a type used to configure the metrics system by registering IMetricsListeners and using rules
+    /// Configures the metrics system by registering IMetricsListeners and using rules
     /// to determine which metrics are enabled.
     /// </summary>
     public interface IMetricsBuilder
     {
         /// <summary>
-        /// The application <see cref="IServiceCollection"/>. This is used by extension methods to register services.
+        /// Gets the application service collection that's used by extension methods to register services.
         /// </summary>
         IServiceCollection Services { get; }
     }

src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Metrics/IMetricsListener.cs

@@ -6,12 +6,12 @@
 namespace Microsoft.Extensions.Diagnostics.Metrics
 {
     /// <summary>
-    /// Represents a type used to listen to metrics emitted from the system.
+    /// Listens to metrics emitted from the system.
     /// </summary>
     public interface IMetricsListener
     {
         /// <summary>
-        /// The name of the listener. This is used to identify the listener in the rules configuration.
+        /// Gets the name of the listener. This is used to identify the listener in the rules configuration.
         /// </summary>
         public string Name { get; }
 
@@ -27,7 +27,7 @@ public interface IMetricsListener
         /// <param name="instrument">The new <see cref="Instrument"/>.</param>
         /// <param name="userState">Listener state associated with this instrument. This will be returned to <see cref="MeasurementCallback{T}"/>
         /// and <see cref="MeasurementsCompleted(Instrument, object?)"/>.</param>
-        /// <returns>Returns true if the listener wants to subscribe to this instrument, otherwise false.</returns>
+        /// <returns><see langword="true" /> if the listener wants to subscribe to this instrument, otherwise <see langword="false" />.</returns>
         public bool InstrumentPublished(Instrument instrument, out object? userState);
 
         /// <summary>

src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Metrics/IObservableInstrumentsSource.cs

@@ -6,13 +6,15 @@
 namespace Microsoft.Extensions.Diagnostics.Metrics
 {
     /// <summary>
-    /// An interface registered with each IMetricsListener using <see cref="IMetricsListener.Initialize(IObservableInstrumentsSource)"/>. The listener
-    /// can call <see cref="RecordObservableInstruments"/> to receive the current set of measurements for enabled observable instruments.
+    /// An interface registered with each IMetricsListener using <see cref="IMetricsListener.Initialize(IObservableInstrumentsSource)"/>.
     /// </summary>
+    /// <remarks>
+    /// The listener can call <see cref="RecordObservableInstruments"/> to receive the current set of measurements for enabled observable instruments.
+    /// </remarks>
     public interface IObservableInstrumentsSource
     {
         /// <summary>
-        /// Requests that the current set of metrics for enabled instruments be sent to the listener's <see cref="MeasurementCallback{T}"/>'s.
+        /// Requests that the current set of metrics for enabled instruments be sent to the listener's <see cref="MeasurementCallback{T}"/> objects.
         /// </summary>
         public void RecordObservableInstruments();
     }

src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Metrics/InstrumentRule.cs

@@ -20,32 +20,41 @@ namespace Microsoft.Extensions.Diagnostics.Metrics
     /// <param name="meterName">The <see cref="Meter.Name">Meter.Name</see> or prefix.</param>
     /// <param name="instrumentName">The <see cref="Instrument.Name">Instrument.Name</see>.</param>
     /// <param name="listenerName">The <see cref="IMetricsListener.Name">IMetricsListener.Name</see>.</param>
-    /// <param name="scopes">The <see cref="MeterScope"/>'s to consider.</param>
-    /// <param name="enable">Enables or disabled the matched instrument for this listener.</param>
+    /// <param name="scopes">A bitwise combination of the enumeration values that specifies the scopes to consider.</param>
+    /// <param name="enable"><see langword="true" /> to enable the matched instrument for this listener; otherwise, <see langword="false" />.</param>
     public class InstrumentRule(string? meterName, string? instrumentName, string? listenerName, MeterScope scopes, bool enable)
     {
         /// <summary>
         /// Gets the <see cref="Meter.Name">Meter.Name</see>, either an exact match or the longest prefix match. Only full segment matches are considered.
-        /// All meters are matched if this is <see langword="null" />.
         /// </summary>
+        /// <value>
+        /// The meter name. If <see langword="null" />, all meters are matched.
+        /// </value>
         public string? MeterName { get; } = meterName;
 
         /// <summary>
         /// Gets the <see cref="Instrument.Name">Instrument.Name</see>, an exact match.
-        /// All instruments for the given meter are matched if this is <see langword="null" />.
         /// </summary>
+        /// <value>
+        /// The instrument name. If <see langword="null" />, all instruments for the meter are matched.
+        /// </value>
         public string? InstrumentName { get; } = instrumentName;
 
         /// <summary>
         /// Gets the <see cref="IMetricsListener.Name">IMetricsListener.Name</see>, an exact match.
-        /// All listeners are matched if this is <see langword="null" />.
         /// </summary>
+        /// <value>
+        /// The listener name. If <see langword="null" />, all listeners are matched.
+        /// </value>
         public string? ListenerName { get; } = listenerName;
 
         /// <summary>
-        /// Gets the <see cref="MeterScope"/>. This is used to distinguish between meters created via <see cref="Meter"/> constructors (<see cref="MeterScope.Global"/>)
-        /// and those created via Dependency Injection with <see cref="IMeterFactory.Create(MeterOptions)"/> (<see cref="MeterScope.Local"/>)."/>.
+        /// Gets the <see cref="MeterScope"/>.
         /// </summary>
+        /// <remarks>
+        /// This property is used to distinguish between meters created via <see cref="Meter"/> constructors (<see cref="MeterScope.Global"/>)
+        /// and those created via Dependency Injection with <see cref="IMeterFactory.Create(MeterOptions)"/> (<see cref="MeterScope.Local"/>).
+        /// </remarks>
         public MeterScope Scopes { get; } = scopes == MeterScope.None
             ? throw new ArgumentOutOfRangeException(nameof(scopes), scopes, "The MeterScope must be Global, Local, or both.")
             : scopes;

src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Metrics/MeasurementHandlers.cs

@@ -6,42 +6,42 @@
 namespace Microsoft.Extensions.Diagnostics.Metrics
 {
     /// <summary>
-    /// A set of supported measurement types. If a listener does not support a given type, the measurement will be skipped.
+    /// Represents a set of supported measurement types. If a listener does not support a given type, the measurement is skipped.
     /// </summary>
     public class MeasurementHandlers
     {
         /// <summary>
-        /// A <see cref="MeasurementCallback{T}"/> for <see cref="byte"/>. If null, byte measurements will be skipped.
+        /// Gets or sets a <see cref="MeasurementCallback{T}"/> for <see cref="byte"/>. If <see langword="null"/>, byte measurements are skipped.
         /// </summary>
         public MeasurementCallback<byte>? ByteHandler { get; set; }
 
         /// <summary>
-        /// A <see cref="MeasurementCallback{T}"/> for <see cref="short"/>. If null, short measurements will be skipped.
+        /// Gets or sets a <see cref="MeasurementCallback{T}"/> for <see cref="short"/>. If <see langword="null"/>, short measurements are skipped.
         /// </summary>
         public MeasurementCallback<short>? ShortHandler { get; set; }
 
         /// <summary>
-        /// A <see cref="MeasurementCallback{T}"/> for <see cref="int"/>. If null, int measurements will be skipped.
+        /// Gets or sets a <see cref="MeasurementCallback{T}"/> for <see cref="int"/>. If <see langword="null"/>, int measurements are skipped.
         /// </summary>
         public MeasurementCallback<int>? IntHandler { get; set; }
 
         /// <summary>
-        /// A <see cref="MeasurementCallback{T}"/> for <see cref="long"/>. If null, long measurements will be skipped.
+        /// Gets or sets a <see cref="MeasurementCallback{T}"/> for <see cref="long"/>. If <see langword="null"/>, long measurements are skipped.
         /// </summary>
         public MeasurementCallback<long>? LongHandler { get; set; }
 
         /// <summary>
-        /// A <see cref="MeasurementCallback{T}"/> for <see cref="float"/>. If null, float measurements will be skipped.
+        /// Gets or sets a <see cref="MeasurementCallback{T}"/> for <see cref="float"/>. If <see langword="null"/>, float measurements are skipped.
         /// </summary>
         public MeasurementCallback<float>? FloatHandler { get; set; }
 
         /// <summary>
-        /// A <see cref="MeasurementCallback{T}"/> for <see cref="double"/>. If null, double measurements will be skipped.
+        /// Gets or sets a <see cref="MeasurementCallback{T}"/> for <see cref="double"/>. If <see langword="null"/>, double measurements are skipped.
         /// </summary>
         public MeasurementCallback<double>? DoubleHandler { get; set; }
 
         /// <summary>
-        /// A <see cref="MeasurementCallback{T}"/> for <see cref="decimal"/>. If null, decimal measurements will be skipped.
+        /// Gets or sets a <see cref="MeasurementCallback{T}"/> for <see cref="decimal"/>. If <see langword="null"/>, decimal measurements are skipped.
         /// </summary>
         public MeasurementCallback<decimal>? DecimalHandler { get; set; }
     }

src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Metrics/MeterScope.cs

@@ -7,14 +7,14 @@
 namespace Microsoft.Extensions.Diagnostics.Metrics
 {
     /// <summary>
-    /// This is used by <see cref="InstrumentRule"/> to distinguish between meters created via <see cref="Meter"/> constructors (<see cref="Global"/>)
-    /// and those created via Dependency Injection with <see cref="IMeterFactory.Create(MeterOptions)"/> (<see cref="Local"/>)."/>.
+    /// Represents scopes used by <see cref="InstrumentRule"/> to distinguish between meters created via <see cref="Meter"/> constructors (<see cref="Global"/>)
+    /// and those created via Dependency Injection with <see cref="IMeterFactory.Create(MeterOptions)"/> (<see cref="Local"/>).
     /// </summary>
     [Flags]
     public enum MeterScope
     {
         /// <summary>
-        /// No scope is specified. This should not be used.
+        /// No scope is specified. This field should not be used.
         /// </summary>
         None = 0,
 

src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Metrics/MetricsBuilderExtensions.Rules.cs

@@ -13,7 +13,7 @@ namespace Microsoft.Extensions.Diagnostics.Metrics
     public static partial class MetricsBuilderExtensions
     {
         /// <summary>
-        /// Enables all <see cref="Instrument"/>'s for the given meter, for all registered <see cref="IMetricsListener"/>'s.
+        /// Enables all instruments for the given meter, for all registered listeners.
         /// </summary>
         /// <param name="builder">The <see cref="IMetricsBuilder"/>.</param>
         /// <param name="meterName">The <see cref="Meter.Name"/> or prefix. A null value matches all meters.</param>
@@ -28,14 +28,14 @@ public static IMetricsBuilder EnableMetrics(this IMetricsBuilder builder, string
         /// <param name="meterName">The <see cref="Meter.Name"/> or prefix. A null value matches all meters.</param>
         /// <param name="instrumentName">The <see cref="Instrument.Name"/>. A null value matches all instruments.</param>
         /// <param name="listenerName">The <see cref="IMetricsListener"/>.Name. A null value matches all listeners.</param>
-        /// <param name="scopes">Indicates which <see cref="MeterScope"/>'s to consider. Default to all scopes.</param>
+        /// <param name="scopes">Indicates which meter scopes to consider. Defaults to all scopes.</param>
         /// <returns>The original <see cref="IMetricsBuilder"/> for chaining.</returns>
         public static IMetricsBuilder EnableMetrics(this IMetricsBuilder builder, string? meterName, string? instrumentName = null, string? listenerName = null,
             MeterScope scopes = MeterScope.Global | MeterScope.Local)
             => builder.ConfigureRule(options => options.EnableMetrics(meterName, instrumentName, listenerName, scopes));
 
         /// <summary>
-        /// Enables all <see cref="Instrument"/>'s for the given meter, for all registered <see cref="IMetricsListener"/>'s.
+        /// Enables all instruments for the given meter, for all registered listeners.
         /// </summary>
         /// <param name="options">The <see cref="MetricsOptions"/>.</param>
         /// <param name="meterName">The <see cref="Meter.Name"/> or prefix. A null value matches all meters.</param>
@@ -50,14 +50,14 @@ public static MetricsOptions EnableMetrics(this MetricsOptions options, string?
         /// <param name="meterName">The <see cref="Meter.Name"/> or prefix. A null value matches all meters.</param>
         /// <param name="instrumentName">The <see cref="Instrument.Name"/>. A null value matches all instruments.</param>
         /// <param name="listenerName">The <see cref="IMetricsListener"/>.Name. A null value matches all listeners.</param>
-        /// <param name="scopes">Indicates which <see cref="MeterScope"/>'s to consider. Default to all scopes.</param>
+        /// <param name="scopes">Indicates which meter scopes to consider. Default to all scopes.</param>
         /// <returns>The original <see cref="MetricsOptions"/> for chaining.</returns>
         public static MetricsOptions EnableMetrics(this MetricsOptions options, string? meterName, string? instrumentName = null, string? listenerName = null,
             MeterScope scopes = MeterScope.Global | MeterScope.Local)
             => options.AddRule(meterName, instrumentName, listenerName, scopes, enable: true);
 
         /// <summary>
-        /// Disables all <see cref="Instrument"/>'s for the given meter, for all registered <see cref="IMetricsListener"/>'s.
+        /// Disables all instruments for the given meter, for all registered listeners.
         /// </summary>
         /// <param name="builder">The <see cref="IMetricsBuilder"/>.</param>
         /// <param name="meterName">The <see cref="Meter.Name"/> or prefix. A null value matches all meters.</param>
@@ -72,14 +72,14 @@ public static IMetricsBuilder DisableMetrics(this IMetricsBuilder builder, strin
         /// <param name="meterName">The <see cref="Meter.Name"/> or prefix. A null value matches all meters.</param>
         /// <param name="instrumentName">The <see cref="Instrument.Name"/>. A null value matches all instruments.</param>
         /// <param name="listenerName">The <see cref="IMetricsListener"/>.Name. A null value matches all listeners.</param>
-        /// <param name="scopes">Indicates which <see cref="MeterScope"/>'s to consider. Default to all scopes.</param>
+        /// <param name="scopes">Indicates which meter scopes to consider. Defaults to all scopes.</param>
         /// <returns>The original <see cref="IMetricsBuilder"/> for chaining.</returns>
         public static IMetricsBuilder DisableMetrics(this IMetricsBuilder builder, string? meterName, string? instrumentName = null, string? listenerName = null,
             MeterScope scopes = MeterScope.Global | MeterScope.Local)
             => builder.ConfigureRule(options => options.DisableMetrics(meterName, instrumentName, listenerName, scopes));
 
         /// <summary>
-        /// Disables all <see cref="Instrument"/>'s for the given meter, for all registered <see cref="IMetricsListener"/>'s.
+        /// Disables all instruments for the given meter, for all registered listeners.
         /// </summary>
         /// <param name="options">The <see cref="MetricsOptions"/>.</param>
         /// <param name="meterName">The <see cref="Meter.Name"/> or prefix. A null value matches all meters.</param>
@@ -94,7 +94,7 @@ public static MetricsOptions DisableMetrics(this MetricsOptions options, string?
         /// <param name="meterName">The <see cref="Meter.Name"/> or prefix. A null value matches all meters.</param>
         /// <param name="instrumentName">The <see cref="Instrument.Name"/>. A null value matches all instruments.</param>
         /// <param name="listenerName">The <see cref="IMetricsListener"/>.Name. A null value matches all listeners.</param>
-        /// <param name="scopes">Indicates which <see cref="MeterScope"/>'s to consider. Default to all scopes.</param>
+        /// <param name="scopes">Indicates which meter scopes to consider. Defaults to all scopes.</param>
         /// <returns>The original <see cref="MetricsOptions"/> for chaining.</returns>
         public static MetricsOptions DisableMetrics(this MetricsOptions options, string? meterName, string? instrumentName = null, string? listenerName = null,
             MeterScope scopes = MeterScope.Global | MeterScope.Local)

src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Metrics/MetricsOptions.cs

@@ -6,12 +6,12 @@
 namespace Microsoft.Extensions.Diagnostics.Metrics
 {
     /// <summary>
-    /// Options for configuring the metrics system.
+    /// Represents options for configuring the metrics system.
     /// </summary>
     public class MetricsOptions
     {
         /// <summary>
-        /// A list of <see cref="InstrumentRule"/>'s that identify which metrics, instruments, and listeners are enabled.
+        /// Gets a list of instrument rules that identifies which metrics, instruments, and listeners are enabled.
         /// </summary>
         public IList<InstrumentRule> Rules { get; } = new List<InstrumentRule>();
     }

src/libraries/Microsoft.Extensions.Diagnostics/src/Metrics/Configuration/MetricsBuilderConfigurationExtensions.cs

@@ -17,7 +17,7 @@ public static class MetricsBuilderConfigurationExtensions
     {
         /// <summary>
         /// Reads metrics configuration from the provided <see cref="IConfiguration"/> section and configures
-        /// which <see cref="Meter"/>'s, <see cref="Instrument"/>'s, and <see cref="IMetricsListener"/>'s are enabled.
+        /// which <see cref="Meter">Meters</see>, <see cref="Instrument">Instruments</see>, and <see cref="IMetricsListener">IMetricsListeners</see> are enabled.
         /// </summary>
         /// <param name="builder">The <see cref="IMetricsBuilder"/>.</param>
         /// <param name="configuration">The <see cref="IConfiguration"/> section to load.</param>

src/libraries/Microsoft.Extensions.Diagnostics/src/Metrics/ConsoleMetrics.cs

@@ -4,12 +4,12 @@
 namespace Microsoft.Extensions.Diagnostics.Metrics
 {
     /// <summary>
-    /// Constants for the Console metrics listener.
+    /// Provides constants for the Console metrics listener.
     /// </summary>
     public static class ConsoleMetrics
     {
         /// <summary>
-        /// The name of the listener used in configuration and enabling instruments.
+        /// Gets the name of the listener used in configuration and enabling instruments.
         /// </summary>
         public static string DebugListenerName => "DebugConsole";
     }