Apply suggestions from code review

Author: IEvangelist

docs/core/diagnostics/metrics-generator.md

@@ -43,9 +43,11 @@ The following example shows a class that declares two metrics. The methods are m
 The code generator runs at build time and provides an implementation of these methods, along with accompanying
 types.
 
-:::code language="csharp" source="snippets/MetricsGen/MetricConstants.cs" id="snippet_metricConstants":::
+:::code language="csharp" source="snippets/MetricsGen/MetricConstants.cs" id="constants":::
 
-:::code language="csharp" source="snippets/MetricsGen/Metrics.cs" id="snippet_Metrics" :::
+The following code demonstrates how to use the generator with primitive types:
+
+:::code language="csharp" source="snippets/MetricsGen/Metrics.cs" id="metrics" :::
 
 The previous declaration automatically returns the following:
 
@@ -74,7 +76,7 @@ internal class Latency
 
 The dimensions specified in the attributes have been turned into arguments to the `Add` and `Record` methods. You then use the generated methods to create instances of these types. With the instances created, you can call `Add` and `Record` to register metric values, as shown in the following example:
 
-:::code language="csharp" source="snippets/MetricsGen/MyClass.cs" id ="snippet_metricCreation":::
+:::code language="csharp" source="snippets/MetricsGen/MyClass.cs" id ="creation":::
 
 ## Metric methods requirements
 

docs/core/diagnostics/metrics-strongly-typed.md

@@ -42,22 +42,25 @@ By default, the source generator derives metric tag names from the field and pro
 
 The following example demonstrates a simple counter metric with one tag. In this scenario, we want to count the number of processed requests and categorize them by a `Region` tag:
 
-:::code language="csharp" source="snippets/MetricsGen/MyMetrics.cs" id= "snippet_SimpleMetricTag":::
+:::code language="csharp" source="snippets/MetricsGen/MyMetrics.cs" id= "tag":::
 
-In the code above, `RequestTags` is a strongly-typed tag struct with a single property `Region`. The `CreateRequestCount` method is marked with <xref:Microsoft.Extensions.Diagnostics.Metrics.CounterAttribute`1> where `T` is an `int`, indicating it generates a **Counter** instrument that tracks `int` values. The attribute references `typeof(RequestTags)`, meaning the counter will use the tags defined in `RequestTags` when recording metrics. The source generator will produce a strongly-typed instrument class (named `RequestCount`) with an `Add` method that accepts integer value and `RequestTags` object.
+In the preceding code, `RequestTags` is a strongly-typed tag struct with a single property `Region`. The `CreateRequestCount` method is marked with <xref:Microsoft.Extensions.Diagnostics.Metrics.CounterAttribute`1> where `T` is an `int`, indicating it generates a `Counter` instrument that tracks `int` values. The attribute references `typeof(RequestTags)`, meaning the counter uses the tags defined in `RequestTags` when recording metrics. The source generator produces a strongly-typed instrument class (named `RequestCount`) with an `Add` method that accepts integer value and `RequestTags` object.
 
 To use the generated metric, create a <xref:System.Diagnostics.Metrics.Meter> and record measurements as shown below:
 
-:::code language="csharp" source="snippets/MetricsGen/MyClass.cs" id ="snippet_SimpleMetricTagUsage":::
+:::code language="csharp" source="snippets/MetricsGen/MyClass.cs" id ="tag":::
 
 In this usage example, calling `MyMetrics.CreateRequestCount(meter)` creates a counter instrument (via the `Meter`) and returns a `RequestCount` metric object. When you call `requestCountMetric.Add(1, tags)`, the metric system records a count of 1 associated with the tag `Region="NorthAmerica"`. You can reuse the `RequestTags` object or create new ones to record counts for different regions, and the tag name `Region` will consistently be applied to every measurement.
 
 ## Example 2: Metric with nested tag objects
 
-For more complex scenarios, you can define tag classes that include multiple tags, nested objects, or even inherited properties. This allows a group of related metrics to share a common set of tags easily. In the next example, we define a set of tag classes and use them for three different metrics:
+For more complex scenarios, you can define tag classes that include multiple tags, nested objects, or even inherited properties. This allows a group of related metrics to effectively share a common set of tags. In the next example, you define a set of tag classes and use them for three different metrics:
 
 :::code language="csharp" source="snippets/MetricsGen/MetricTags.cs" :::
-:::code language="csharp" source="snippets/MetricsGen/Metrics.cs" id="snippet_MetricTags" :::
+
+The preceding code defines the metric inheritance and object shapes. The following code demonstrates how to use these shapes with the generator, as shown in the `Metric` class:
+
+:::code language="csharp" source="snippets/MetricsGen/Metrics.cs" id="tags" :::
 
 In this example, `MetricTags` is a tag class that inherits from `MetricParentTags` and also contains a nested tag object (`MetricChildTags`) and a nested struct (`MetricTagsStruct`). The tag properties demonstrate both default and customized tag names:
 
@@ -71,7 +74,7 @@ All three metric definitions `CreateLatency`, `CreateTotalCount`, and `CreateTot
 
 The following code shows how to create and use these metrics in a class:
 
-:::code language="csharp" source="snippets/MetricsGen/MyClass.cs" id ="snippet_strongMetricCreation":::
+:::code language="csharp" source="snippets/MetricsGen/MyClass.cs" id ="creation":::
 
 In the preceding `MyClass.DoWork` method, a `MetricTags` object is populated with values for each tag. This single `tags` object is then passed to all three instruments when recording data. The `Latency` metric (a histogram) records the elapsed time, and both counters (`TotalCount` and `TotalFailures`) record occurrence counts. Because all metrics share the same tag object type, the tags (`Dim1DimensionName`, `Operation`, `Dim2`, `Dim3`, `DimensionNameOfParentOperation`) are present on every measurement.
 

docs/core/diagnostics/snippets/MetricsGen/MetricConstants.cs

@@ -1,12 +1,12 @@
 namespace MetricsGen;
 
-//<snippet_metricConstants>
+// <constants>
 internal class MetricConstants
 {
     public const string EnvironmentName = "env";
     public const string Region = "region";
     public const string RequestName = "requestName";
     public const string RequestStatus = "requestStatus";
 }
-// </snippet_metricConstants>
+// </constants>
 

docs/core/diagnostics/snippets/MetricsGen/MetricTags.cs

@@ -1,6 +1,7 @@
 using Microsoft.Extensions.Diagnostics.Metrics;
 
 namespace MetricsGen;
+
 public class MetricTags : MetricParentTags
 {
     [TagName("Dim1DimensionName")]

docs/core/diagnostics/snippets/MetricsGen/Metrics.cs

@@ -1,7 +1,7 @@
 #define FIRST // FIRST SECOND
 
 #if FIRST
-//<snippet_Metrics>
+// <metrics>
 using System.Diagnostics.Metrics;
 using Microsoft.Extensions.Diagnostics.Metrics;
 
@@ -20,11 +20,11 @@ internal static partial class Metric
     [Counter<int>]
     public static partial TotalFailures CreateTotalFailures(this Meter meter);
 }
-//</snippet_Metrics>
+// </metrics>
 #elif SECOND
 
 using MetricsGen;
-//<snippet_MetricTags>
+// <tags>
 using System.Diagnostics.Metrics;
 using Microsoft.Extensions.Diagnostics.Metrics;
 
@@ -39,5 +39,5 @@ public static partial class Metric
     [Counter<int>(typeof(MetricTags))]
     public static partial TotalFailures CreateTotalFailures(Meter meter);
 }
-//</snippet_MetricTags>
+// </tags>
 #endif

docs/core/diagnostics/snippets/MetricsGen/MyClass.cs

@@ -4,7 +4,7 @@
 
 namespace MetricsGen;
 
-// <snippet_metricCreation>
+// <creation>
 internal class MyClass
 {
     private string envName = "envValue";
@@ -50,16 +50,15 @@ public void ReportSampleFailuresCount()
         _totalFailuresMetric.Add(1);
     }
 }
-//</snippet_metricCreation>
+// </creation>
 
 #elif SECOND
 
 using System.Diagnostics;
 using System.Diagnostics.Metrics;
 using MetricsGen;
 
-// <snippet_strongMetricCreation>
-
+// <creation>
 internal class MyClass
 { 
     private readonly Latency _latencyMetric;
@@ -76,11 +75,10 @@ public MyClass(Meter meter)
 
     public void DoWork()
     {
-        var stopwatch = new Stopwatch();
-        stopwatch.Start();
+        var startingTimestamp = Stopwatch.GetTimestamp();
         bool requestSuccessful = true;
-        // ... perform some operation ...
-        stopwatch.Stop();
+        // Perform some operation to measure
+        var elapsedTime = Stopwatch.GetElapsedTime(startingTimestamp);
 
         // Create a tag object with values for all tags
         var tags = new MetricTags
@@ -99,22 +97,22 @@ public void DoWork()
         };
 
         // Record the metric values with the associated tags
-        _latencyMetric.Record(stopwatch.ElapsedMilliseconds, tags);
+        _latencyMetric.Record(elapsedTime.ElapsedMilliseconds, tags);
         _totalCountMetric.Add(1, tags);
         if (!requestSuccessful)
         {
             _totalFailuresMetric.Add(1, tags);
         }
     }
 }
-// </snippet_strongMetricCreation>
+// </creation>
 #elif THIRD
 
 using MetricsGen;
 using System.Diagnostics.Metrics;
 
-//<snippet_SimpleMetricTagUsage>
-Meter meter = new Meter("MyCompany.MyApp", "1.0");
+// <tag>
+Meter meter = new("MyCompany.MyApp", "1.0");
 RequestCount requestCountMetric = MyMetrics.CreateRequestCount(meter);
 
 // Create a tag object with the relevant tag value
@@ -123,5 +121,5 @@ public void DoWork()
 // Record a metric value with the associated tag
 requestCountMetric.Add(1, tags);
 
-//</snippet_SimpleMetricTagUsage>
+// </tag>
 #endif

docs/core/diagnostics/snippets/MetricsGen/MyMetrics.cs

@@ -2,7 +2,7 @@
 using Microsoft.Extensions.Diagnostics.Metrics;
 
 namespace MetricsGen;
-//<snippet_SimpleMetricTag>
+// <tag>
 public struct RequestTags
 {
     public string Region { get; set; }
@@ -13,4 +13,4 @@ public static partial class MyMetrics
     [Counter<int>(typeof(RequestTags))]
     public static partial RequestCount CreateRequestCount(Meter meter);
 }
-//</snippet_SimpleMetricTag>
+// </tag>