Add see also links to conceptual docs (#7510)

Author: gewarren

xml/System.Diagnostics.Metrics/Counter`1.xml

@@ -27,16 +27,17 @@
   <Interfaces />
   <Docs>
     <typeparam name="T">The type that the counter represents.</typeparam>
-    <summary>Represents an instrument that supports adding non-negative values. For example, you might call counter.Add(1) each time a request is processed to track the total number of requests. Most metric viewers display counters using a rate (requests/sec), by default, but can also display a cumulative total.</summary>
+    <summary>Represents an instrument that supports adding non-negative values. For example, you might call <c>counter.Add(1)</c> each time a request is processed to track the total number of requests. Most metric viewers display counters using a rate (requests/sec), by default, but can also display a cumulative total.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>
+This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>.
 
       ]]></format>
     </remarks>
+    <related type="Article" href="/dotnet/core/diagnostics/metrics-instrumentation">Creating metrics</related>
   </Docs>
   <Members>
     <Member MemberName="Add">
@@ -59,7 +60,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
       </Parameters>
       <Docs>
         <param name="delta">The increment measurement.</param>
-        <summary>Record the increment value of the measurement.</summary>
+        <summary>Records the increment value of the measurement.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -85,7 +86,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <param name="delta">The increment measurement.</param>
         <param name="tag">A key-value pair tag associated with the measurement.</param>
-        <summary>Record the increment value of the measurement.</summary>
+        <summary>Records the increment value of the measurement.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -118,7 +119,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <param name="delta">The increment measurement.</param>
         <param name="tags">A list of key-value pair tags associated with the measurement.</param>
-        <summary>Record the increment value of the measurement.</summary>
+        <summary>Records the increment value of the measurement.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -177,7 +178,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <param name="delta">The increment measurement.</param>
         <param name="tags">A span of key-value pair tags associated with the measurement.</param>
-        <summary>Record the increment value of the measurement.</summary>
+        <summary>Records the increment value of the measurement.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -205,7 +206,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
         <param name="delta">The increment measurement.</param>
         <param name="tag1">A first key-value pair tag associated with the measurement.</param>
         <param name="tag2">A second key-value pair tag associated with the measurement.</param>
-        <summary>Record the increment value of the measurement.</summary>
+        <summary>Records the increment value of the measurement.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -235,7 +236,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
         <param name="tag1">A first key-value pair tag associated with the measurement.</param>
         <param name="tag2">A second key-value pair tag associated with the measurement.</param>
         <param name="tag3">A third key-value pair tag associated with the measurement.</param>
-        <summary>Record the increment value of the measurement.</summary>
+        <summary>Records the increment value of the measurement.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Diagnostics.Metrics/Histogram`1.xml

@@ -27,18 +27,17 @@
   <Interfaces />
   <Docs>
     <typeparam name="T">The type that the histogram represents.</typeparam>
-    <summary>Represents a metrics Instrument that can be used to report arbitrary values that are likely to be statistically meaningful.
-            e.g. the request duration.
-            Use <see cref="M:System.Diagnostics.Metrics.Meter.CreateHistogram``1(System.String,System.String,System.String)" /> method to create the Histogram object.</summary>
+    <summary>Represents a metrics instrument that can be used to report arbitrary values that are likely to be statistically meaningful, for example, the request duration. Call <see cref="M:System.Diagnostics.Metrics.Meter.CreateHistogram``1(System.String,System.String,System.String)" /> to create a Histogram object.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>
+This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>.
 
       ]]></format>
     </remarks>
+    <related type="Article" href="/dotnet/core/diagnostics/metrics-instrumentation">Creating metrics</related>
   </Docs>
   <Members>
     <Member MemberName="Record">
@@ -61,7 +60,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
       </Parameters>
       <Docs>
         <param name="value">The measurement value.</param>
-        <summary>Record a measurement value.</summary>
+        <summary>Records a measurement value.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -87,7 +86,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <param name="value">The measurement value.</param>
         <param name="tag">A key-value pair tag associated with the measurement.</param>
-        <summary>Record a measurement value.</summary>
+        <summary>Records a measurement value.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -120,7 +119,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <param name="value">The measurement value.</param>
         <param name="tags">A list of key-value pair tags associated with the measurement.</param>
-        <summary>Record a measurement value.</summary>
+        <summary>Records a measurement value.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -179,7 +178,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <param name="value">The measurement value.</param>
         <param name="tags">A span of key-value pair tags associated with the measurement.</param>
-        <summary>Record a measurement value.</summary>
+        <summary>Records a measurement value.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -207,7 +206,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
         <param name="value">The measurement value.</param>
         <param name="tag1">A first key-value pair tag associated with the measurement.</param>
         <param name="tag2">A second key-value pair tag associated with the measurement.</param>
-        <summary>Record a measurement value.</summary>
+        <summary>Records a measurement value.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -237,7 +236,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
         <param name="tag1">A first key-value pair tag associated with the measurement.</param>
         <param name="tag2">A second key-value pair tag associated with the measurement.</param>
         <param name="tag3">A third key-value pair tag associated with the measurement.</param>
-        <summary>Record a measurement value.</summary>
+        <summary>Records a measurement value.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Diagnostics.Metrics/Meter.xml

@@ -20,6 +20,7 @@
   <Docs>
     <summary>Meter is the class responsible for creating and tracking the Instruments.</summary>
     <remarks>To be added.</remarks>
+    <related type="Article" href="/dotnet/core/diagnostics/metrics-instrumentation">Tutorial: Create metrics</related>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

xml/System.Diagnostics.Metrics/ObservableCounter`1.xml

@@ -27,18 +27,17 @@
   <Interfaces />
   <Docs>
     <typeparam name="T">The type that the observable counter represents.</typeparam>
-    <summary>ObservableCounter is a metrics observable Instrument which reports monotonically increasing value(s) when the instrument is being observed.
-            e.g. CPU time (for different processes, threads, user mode or kernel mode).
-            Use Meter.CreateObservableCounter methods to create the observable counter object.</summary>
+    <summary>Represents a metrics-observable instrument that reports monotonically increasing values when the instrument is being observed, for example, CPU time (for different processes, threads, user mode, or kernel mode). Call <see cref="Overload:System.Diagnostics.Metrics.Meter.CreateObservableCounter" /> to create the observable counter object.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>
+This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>.
 
       ]]></format>
     </remarks>
+    <related type="Article" href="/dotnet/core/diagnostics/metrics-instrumentation">Creating metrics</related>
   </Docs>
   <Members>
     <Member MemberName="Observe">

xml/System.Diagnostics.Metrics/ObservableGauge`1.xml

@@ -27,17 +27,17 @@
   <Interfaces />
   <Docs>
     <typeparam name="T">To be added.</typeparam>
-    <summary>ObservableGauge is an observable Instrument that reports non-additive value(s) when the instrument is being observed.
-            e.g. the current room temperature Use Meter.CreateObservableGauge methods to create the observable counter object.</summary>
+    <summary>Represents an observable instrument that reports non-additive values when the instrument is being observed, for example, the current room temperature. Call <see cref="Overload:System.Diagnostics.Metrics.Meter.CreateObservableGauge" /> to create the observable counter object.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>
+This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>.
 
       ]]></format>
     </remarks>
+    <related type="Article" href="/dotnet/core/diagnostics/metrics-instrumentation">Creating metrics</related>
   </Docs>
   <Members>
     <Member MemberName="Observe">
@@ -57,8 +57,8 @@ This class supports only the following generic parameter types: <xref:System.Byt
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>Observe() fetches the current measurements being tracked by this observable counter.</summary>
-        <returns>To be added.</returns>
+        <summary>Fetches the current measurements being tracked by this observable counter.</summary>
+        <returns>An enumeration of measurements of type `<typeparamref name="T"/>` that are being tracked by this observable counter.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Diagnostics.Tracing/EventCounter.xml

@@ -68,6 +68,7 @@ For an example of how to use the <xref:System.Diagnostics.Tracing.EventCounter>
 
    ]]></format>
     </remarks>
+    <related type="Article" href="/dotnet/core/diagnostics/event-counters">EventCounters in .NET</related>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml

@@ -43,6 +43,7 @@
 
     ]]></format>
     </remarks>
+    <related type="Article" href="/dotnet/core/diagnostics/event-counters">EventCounters in .NET</related>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml

@@ -47,6 +47,7 @@ For an example that uses <xref:System.Diagnostics.Tracing.IncrementingPollingCou
 
     ]]></format>
     </remarks>
+    <related type="Article" href="/dotnet/core/diagnostics/event-counters">EventCounters in .NET</related>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

xml/System.Diagnostics.Tracing/PollingCounter.xml

@@ -47,6 +47,7 @@ For an example that uses <xref:System.Diagnostics.Tracing.PollingCounter> inside
 
       ]]></format>
     </remarks>
+    <related type="Article" href="/dotnet/core/diagnostics/event-counters">EventCounters in .NET</related>
   </Docs>
   <Members>
     <Member MemberName=".ctor">