PR feedback

Author: jack-berg

doc-snippets/api/src/main/java/otel/AsyncCounterUsage.java

@@ -23,7 +23,7 @@ public static void asyncCounterUsage(Meter meter) {
             .counterBuilder("fully.qualified.counter")
             .setDescription("A count of produced widgets")
             .setUnit("{widget}")
-            // optionally change the type to double
+            // Uncomment to optionally change the type to double
             // .ofDoubles()
             .buildWithCallback(
                 // the callback is invoked a MetricReader reads metrics

doc-snippets/api/src/main/java/otel/AsyncGaugeUsage.java

@@ -22,7 +22,7 @@ public static void asyncGaugeUsage(Meter meter) {
             .gaugeBuilder("fully.qualified.gauge")
             .setDescription("The current temperature of the widget processing line")
             .setUnit("K")
-            // optionally change the type to long
+            // Uncomment to optionally change the type to long
             // .ofLongs()
             .buildWithCallback(
                 // the callback is invoked a MetricReader reads metrics

doc-snippets/api/src/main/java/otel/AsyncUpDownCounterUsage.java

@@ -22,7 +22,7 @@ public static void asyncUpDownCounterUsage(Meter meter) {
             .upDownCounterBuilder("fully.qualified.updowncounter")
             .setDescription("Current length of widget processing queue")
             .setUnit("{widget}")
-            // optionally change the type to double
+            // Uncomment to optionally change the type to double
             // .ofDoubles()
             .buildWithCallback(
                 // the callback is invoked a MetricReader reads metrics

doc-snippets/api/src/main/java/otel/AttributesUsage.java

@@ -36,7 +36,7 @@ public static void attributesUsage() {
             .put(SHOP_NAME, "opentelemetry-demo")
             .put(CUSTOMER_ID, 123)
             .put(CUSTOMER_NAME, "Jack")
-            // optionally initialize attribute keys on the fly
+            // Optionally initialize attribute keys on the fly
             .put(AttributeKey.stringKey("com.acme.string-key"), "value")
             .put(AttributeKey.booleanKey("com.acme.bool-key"), true)
             .put(AttributeKey.longKey("com.acme.long-key"), 1L)
@@ -45,7 +45,7 @@ public static void attributesUsage() {
             .put(AttributeKey.booleanArrayKey("come.acme.bool-array-key"), true, false)
             .put(AttributeKey.longArrayKey("come.acme.long-array-key"), 1L, 2L)
             .put(AttributeKey.doubleArrayKey("come.acme.double-array-key"), 1.1, 2.2)
-            // optionally omit initializing AttributeKey
+            // Optionally omit initializing AttributeKey
             .put("com.acme.string-key", "value")
             .put("com.acme.bool-key", true)
             .put("come.acme.long-key", 1L)

doc-snippets/api/src/main/java/otel/BaggageUsage.java

@@ -28,7 +28,7 @@ public static void baggageUsage() {
             .put("shopId", "abc123")
             .put("shopName", "opentelemetry-demo", BaggageEntryMetadata.create("metadata"))
             .build();
-    // ...or start from empty
+    // ...or uncomment to start from empty
     // newBaggage = Baggage.empty().toBuilder().put("shopId", "abc123").build();
     // output => new baggage: {shopId=abc123(), shopName=opentelemetry-demo(metadata)}
     System.out.println("new baggage: " + asString(newBaggage));

doc-snippets/api/src/main/java/otel/GaugeUsage.java

@@ -21,7 +21,7 @@ public static void gaugeUsage(Meter meter) {
             .gaugeBuilder("fully.qualified.gauge")
             .setDescription("The current temperature of the widget processing line")
             .setUnit("K")
-            // optionally change the type to long
+            // Uncomment to optionally change the type to long
             // .ofLongs()
             .build();
 

doc-snippets/api/src/main/java/otel/HistogramUsage.java

@@ -20,9 +20,9 @@ public static void histogramUsage(Meter meter) {
             .histogramBuilder("fully.qualified.histogram")
             .setDescription("Length of time to process a widget")
             .setUnit("s")
-            // optionally provide advice on useful default explicit bucket boundaries
+            // Uncomment to optionally provide advice on useful default explicit bucket boundaries
             // .setExplicitBucketBoundariesAdvice(Arrays.asList(1.0, 2.0, 3.0))
-            // optionally change the type to long
+            // Uncomment to optionally change the type to long
             // .ofLongs()
             .build();
 

doc-snippets/api/src/main/java/otel/LogRecordUsage.java

@@ -54,7 +54,8 @@ public static void logRecordUsage(Logger logger) {
         .setAttribute(
             AttributeKey.doubleArrayKey("come.acme.double-array-key"), Arrays.asList(1.1, 2.2))
         .setAllAttributes(WIDGET_RED_CIRCLE)
-        // Optionally explicitly set the context used to correlate with spans. If omitted,
+        // Uncomment to optionally explicitly set the context used to correlate with spans. If
+        // omitted,
         // Context.current() is used.
         // .setContext(context)
         // Emit the log record

doc-snippets/api/src/main/java/otel/SemanticAttributesUsage.java

@@ -7,7 +7,7 @@
 
 public class SemanticAttributesUsage {
   public static void semanticAttributesUsage() {
-    // Semantic attributes are organized by top level domain and whether they are stable or
+    // Semantic attributes are organized by top-level domain and whether they are stable or
     // incubating.
     // For example:
     // - stable attributes starting with http.* are in the HttpAttributes class.

doc-snippets/api/src/main/java/otel/SpanUsage.java

@@ -36,16 +36,17 @@ public static void spanUsage(Tracer tracer) {
                 AttributeKey.longArrayKey("come.acme.long-array-key"), Arrays.asList(1L, 2L))
             .setAttribute(
                 AttributeKey.doubleArrayKey("come.acme.double-array-key"), Arrays.asList(1.1, 2.2))
-            // optionally omit initializing AttributeKey
+            // Optionally omit initializing AttributeKey
             .setAttribute("com.acme.string-key", "value")
             .setAttribute("com.acme.bool-key", true)
             .setAttribute("come.acme.long-key", 1L)
             .setAttribute("come.acme.double-key", 1.1)
             .setAllAttributes(WIDGET_RED_CIRCLE)
-            // Optionally explicitly set the parent span context. If omitted, the span's parent will
+            // Uncomment to optionally explicitly set the parent span context. If omitted, the
+            // span's parent will
             // be set using Context.current()
             // .setParent(parentContext)
-            // Optionally add links
+            // Uncomment to optionally add links
             // .addLink(linkContext, linkAttributes)
             // Start the span
             .startSpan();