Apply suggestions from code review

tarekgh · carlossanlop · web-flow · commit e0233810e7b6 · 2023-10-27T15:29:34.000-07:00
Co-authored-by: Carlos Sánchez López &lt;1175054+carlossanlop@users.noreply.github.com&gt;
diff --git a/xml/System.Diagnostics.Metrics/IMeterFactory.xml b/xml/System.Diagnostics.Metrics/IMeterFactory.xml
@@ -16,11 +16,15 @@
   </Interfaces>
   <Docs>
     <summary>A factory for creating <see cref="T:System.Diagnostics.Metrics.Meter" /> instances.</summary>
-    <remarks>Meter factories will be accountable for the following responsibilities:
- - Creating a new meter.
- - Attaching the factory instance as a scope to the Meter constructor for all created Meter objects.
- - Storing created meters in a cache and returning a cached instance if a meter with the same parameters (name, version, and tags) is requested.
- - Disposing of all cached Meter objects upon factory disposal.</remarks>
+    <remarks>
+      <para>Meter factories will be accountable for the following responsibilities:</para>
+      <ul>
+        <li>Creating a new meter.</li>
+        <li>Attaching the factory instance as a scope to the Meter constructor for all created Meter objects.</li>
+        <li>Storing created meters in a cache and returning a cached instance if a meter with the same parameters (name, version, and tags) is requested.</li>
+        <li>Disposing of all cached Meter objects upon factory disposal.</li>
+      </ul>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="Create">
diff --git a/xml/System.Diagnostics.Metrics/Instrument.xml b/xml/System.Diagnostics.Metrics/Instrument.xml
@@ -116,12 +116,11 @@
       <Docs>
         <param name="meter">The meter that created the instrument.</param>
         <param name="name">The instrument name. cannot be <see langword="null" />.</param>
-        <param name="unit">Optional instrument unit of measurements.</param>
-        <param name="description">Optional instrument description.</param>
-        <param name="tags">Optional instrument tags.</param>
-        <summary>Protected constructor to initialize the common instrument properties like the meter, name, description, and unit.
- All classes extending Instrument need to call this constructor when constructing object of the extended class.</summary>
-        <remarks>To be added.</remarks>
+        <param name="unit">An optional instrument unit of measurements.</param>
+        <param name="description">An optional instrument description.</param>
+        <param name="tags">An optional instrument tags.</param>
+        <summary>Protected constructor to initialize the common instrument properties like the meter, name, description, and unit.</summary>
+        <remarks> All classes extending <see cref="T:System.Diagnostics.Metrics.Instrument"/> need to call this constructor when constructing an object of the extended class.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Description">
diff --git a/xml/System.Diagnostics.Metrics/Instrument`1.xml b/xml/System.Diagnostics.Metrics/Instrument`1.xml
@@ -136,12 +136,11 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <param name="meter">The meter that created the instrument.</param>
         <param name="name">The instrument name. cannot be <see langword="null" />.</param>
-        <param name="unit">Optional instrument unit of measurements.</param>
-        <param name="description">Optional instrument description.</param>
-        <param name="tags">Optional instrument tags.</param>
-        <summary>Create the metrics instrument using the properties meter, name, description, and unit.
- All classes extending Instrument{T} need to call this constructor when constructing object of the extended class.</summary>
-        <remarks>To be added.</remarks>
+        <param name="unit">An optional instrument unit of measurements.</param>
+        <param name="description">An optional instrument description.</param>
+        <param name="tags">An optional instrument tags.</param>
+        <summary>Creates a metrics instrument instance using the properties meter, name, description, and unit.</summary>
+        <remarks>All classes extending <see cref=""T:System.Diagnostics.Metrics.Instrument`1""/> need to call this constructor when constructing an object of the extended class.</remarks>
       </Docs>
     </Member>
     <Member MemberName="RecordMeasurement">
diff --git a/xml/System.Diagnostics.Metrics/Meter.xml b/xml/System.Diagnostics.Metrics/Meter.xml
@@ -166,9 +166,7 @@
         <param name="tags">The optional Meter tags.</param>
         <param name="scope">The optional Meter scope.</param>
         <summary>Initializes a new instance of the Meter using the meter name and version.</summary>
-        <remarks>You can use the scope object to link several Meters with a particular scope.
- For instance, a dependency injection container can choose to associate all Meters that are created within the container with its own scope.
- If the scope object is <see langword="null" />, it indicates that the Meter is not linked to any particular scope.</remarks>
+        <remarks>You can use the scope object to link several Meters with a particular scope. For instance, a dependency injection container can choose to associate all Meters that are created within the container with its own scope. If the scope object is <see langword="null" />, it indicates that the Meter is not linked to any particular scope.</remarks>
       </Docs>
     </Member>
     <Member MemberName="CreateCounter&lt;T&gt;">
@@ -296,14 +294,23 @@ Counter is an instrument that supports non-negative increments. Example uses for
       </Parameters>
       <Docs>
         <typeparam name="T">To be added.</typeparam>
-        <param name="name">The instrument name. cannot be <see langword="null" />.</param>
-        <param name="unit">Optional instrument unit of measurements.</param>
-        <param name="description">Optional instrument description.</param>
-        <param name="tags">tags to attach to the counter.</param>
-        <summary>Create a metrics Counter object.</summary>
+        <param name="name">The instrument name. It cannot be <see langword="null" />.</param>
+        <param name="unit">An optional instrument unit of measurements.</param>
+        <param name="description">An optional instrument description.</param>
+        <param name="tags">The tags to attach to the counter.</param>
+        <summary>Creates a metrics Counter object.</summary>
         <returns>To be added.</returns>
-        <remarks>Counter is an Instrument which supports non-negative increments.
- Example uses for Counter: count the number of bytes received, count the number of requests completed, count the number of accounts created, count the number of checkpoints run, and count the number of HTTP 5xx errors.</remarks>
+        <remarks>
+          <para>Counter is an Instrument that supports non-negative increments.</para>
+          <para>Example uses for Counter:</para>
+            <ul>
+              <li>Count the number of bytes received.</li>
+              <li>Count the number of requests completed.</li>
+              <li>Count the number of accounts created.</li>
+              <li>Count the number of checkpoints run.</li>
+              <li>Count the number of HTTP 5xx errors.</li>
+            </ul>
+          </remarks>
       </Docs>
     </Member>
     <Member MemberName="CreateHistogram&lt;T&gt;">
@@ -425,11 +432,11 @@ Example uses for Histogram: The request duration and the size of the response pa
       </Parameters>
       <Docs>
         <typeparam name="T">To be added.</typeparam>
-        <param name="name">The instrument name. cannot be <see langword="null" />.</param>
-        <param name="unit">Optional instrument unit of measurements.</param>
-        <param name="description">Optional instrument description.</param>
-        <param name="tags">tags to attach to the counter.</param>
-        <summary>Histogram is an Instrument which can be used to report arbitrary values that are likely to be statistically meaningful. It is intended for statistics such as histograms, summaries, and percentile.</summary>
+        <param name="name">The instrument name. It cannot be <see langword="null" />.</param>
+        <param name="unit">An optional instrument unit of measurements.</param>
+        <param name="description">An optional instrument description.</param>
+        <param name="tags">The tags to attach to the counter.</param>
+        <summary>Creates an Histogram instance, which is an Instrument that can be used to report arbitrary values that are likely to be statistically meaningful. It is intended for statistics such as histograms, summaries, and percentile.</summary>
         <returns>To be added.</returns>
         <remarks>Example uses for Histogram: the request duration and the size of the response payload.</remarks>
       </Docs>
@@ -710,12 +717,12 @@ Example uses for ObservableCounter: The number of page faults for each process.
       </Parameters>
       <Docs>
         <typeparam name="T">To be added.</typeparam>
-        <param name="name">The instrument name. cannot be <see langword="null" />.</param>
+        <param name="name">The instrument name. It cannot be <see langword="null" />.</param>
         <param name="observeValues">The callback to call to get the measurements when the <see cref="M:System.Diagnostics.Metrics.ObservableInstrument`1.Observe" /> is called by <see cref="M:System.Diagnostics.Metrics.MeterListener.RecordObservableInstruments" />.</param>
-        <param name="unit">Optional instrument unit of measurements.</param>
-        <param name="description">Optional instrument description.</param>
-        <param name="tags">tags to attach to the counter.</param>
-        <summary>ObservableCounter is an Instrument which reports monotonically increasing value(s) when the instrument is being observed.</summary>
+        <param name="unit">An optional instrument unit of measurements.</param>
+        <param name="description">An optional instrument description.</param>
+        <param name="tags">The tags to attach to the counter.</param>
+        <summary>Creates an ObservableCounter instance, which is an Instrument that reports monotonically increasing value(s) when the instrument is being observed.</summary>
         <returns>To be added.</returns>
         <remarks>Example uses for ObservableCounter: The number of page faults for each process.</remarks>
       </Docs>
@@ -786,12 +793,12 @@ Example uses for ObservableCounter: The number of page faults for each process.
       </Parameters>
       <Docs>
         <typeparam name="T">To be added.</typeparam>
-        <param name="name">The instrument name. cannot be <see langword="null" />.</param>
+        <param name="name">The instrument name. It cannot be <see langword="null" />.</param>
         <param name="observeValue">The callback to call to get the measurements when the <see cref="M:System.Diagnostics.Metrics.ObservableInstrument`1.Observe" /> is called by <see cref="M:System.Diagnostics.Metrics.MeterListener.RecordObservableInstruments" /></param>
-        <param name="unit">Optional instrument unit of measurements.</param>
-        <param name="description">Optional instrument description.</param>
-        <param name="tags">tags to attach to the counter.</param>
-        <summary>ObservableCounter is an Instrument which reports monotonically increasing value(s) when the instrument is being observed.</summary>
+        <param name="unit">An optional instrument unit of measurements.</param>
+        <param name="description">An optional instrument description.</param>
+        <param name="tags">The tags to attach to the counter.</param>
+        <summary>Creates an ObservableCounter instance, which is an Instrument that reports monotonically increasing value(s) when the instrument is being observed.</summary>
         <returns>To be added.</returns>
         <remarks>Example uses for ObservableCounter: The number of page faults for each process.</remarks>
       </Docs>
@@ -862,12 +869,12 @@ Example uses for ObservableCounter: The number of page faults for each process.
       </Parameters>
       <Docs>
         <typeparam name="T">To be added.</typeparam>
-        <param name="name">The instrument name. cannot be <see langword="null" />.</param>
+        <param name="name">The instrument name. It cannot be <see langword="null" />.</param>
         <param name="observeValue">The callback to call to get the measurements when the <see cref="M:System.Diagnostics.Metrics.ObservableInstrument`1.Observe" /> is called by <see cref="M:System.Diagnostics.Metrics.MeterListener.RecordObservableInstruments" />.</param>
-        <param name="unit">Optional instrument unit of measurements.</param>
-        <param name="description">Optional instrument description.</param>
-        <param name="tags">tags to attach to the counter.</param>
-        <summary>ObservableCounter is an Instrument which reports monotonically increasing value(s) when the instrument is being observed.</summary>
+        <param name="unit">An optional instrument unit of measurements.</param>
+        <param name="description">An optional instrument description.</param>
+        <param name="tags">The tags to attach to the counter.</param>
+        <summary>Creates an ObservableCounter instance, which is an Instrument that reports monotonically increasing value(s) when the instrument is being observed.</summary>
         <returns>To be added.</returns>
         <remarks>Example uses for ObservableCounter: The number of page faults for each process.</remarks>
       </Docs>
@@ -1124,14 +1131,14 @@ Example uses for ObservableCounter: The number of page faults for each process.
       </Parameters>
       <Docs>
         <typeparam name="T">To be added.</typeparam>
-        <param name="name">The instrument name. cannot be <see langword="null" />.</param>
+        <param name="name">The instrument name. It cannot be <see langword="null" />.</param>
         <param name="observeValues">The callback to call to get the measurements when the <see cref="M:System.Diagnostics.Metrics.ObservableInstrument`1.Observe" /> is called by <see cref="M:System.Diagnostics.Metrics.MeterListener.RecordObservableInstruments" />.</param>
-        <param name="unit">Optional instrument unit of measurements.</param>
-        <param name="description">Optional instrument description.</param>
-        <param name="tags">tags to attach to the counter.</param>
-        <summary>ObservableGauge is an asynchronous Instrument which reports non-additive value(s) (e.g. the room temperature - it makes no sense to report the temperature value from multiple rooms and sum them up) when the instrument is being observed.</summary>
+        <param name="unit">An optional instrument unit of measurements.</param>
+        <param name="description">An optional instrument description.</param>
+        <param name="tags">The tags to attach to the counter.</param>
+        <summary>Creates an ObservableGauge instance, which is an asynchronous Instrument that reports non-additive value(s) when the instrument is being observed.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>For example: The room temperature - it makes no sense to report the temperature value from multiple rooms and sum them up.</remarks>
       </Docs>
     </Member>
     <Member MemberName="CreateObservableGauge&lt;T&gt;">
diff --git a/xml/System.Diagnostics.Metrics/MeterOptions.xml b/xml/System.Diagnostics.Metrics/MeterOptions.xml
@@ -24,7 +24,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>Options for creating a <see cref="T:System.Diagnostics.Metrics.Meter" />.</summary>
+    <summary>The options for creating a <see cref="T:System.Diagnostics.Metrics.Meter" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
diff --git a/xml/System.Diagnostics.Metrics/ObservableInstrument`1.xml b/xml/System.Diagnostics.Metrics/ObservableInstrument`1.xml
@@ -137,12 +137,11 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <param name="meter">The meter that created the instrument.</param>
         <param name="name">The instrument name. cannot be <see langword="null" />.</param>
-        <param name="unit">Optional instrument unit of measurements.</param>
-        <param name="description">Optional instrument description.</param>
-        <param name="tags">tags to attach to the counter.</param>
-        <summary>Create the metrics observable instrument using the properties meter, name, description, and unit.
- All classes extending ObservableInstrument{T} need to call this constructor when constructing object of the extended class.</summary>
-        <remarks>To be added.</remarks>
+        <param name="unit">An optional instrument unit of measurements.</param>
+        <param name="description">An optional instrument description.</param>
+        <param name="tags">The tags to attach to the counter.</param>
+        <summary>Creates a metrics observable instrument instance using the specified meter, name, description, and unit.</summary>
+        <remarks>All classes extending <see cref="T:System.Diagnostics.Metrics.ObservableInstrument`1"/> need to call this constructor when constructing an object of the extended class.</remarks>
       </Docs>
     </Member>
     <Member MemberName="IsObservable">
