[sdk-metrics] XML doc tweaks for exemplar experimental APIs (#5392)

open-telemetry · Feb 27, 2024 · 4443223 · 4443223
1 parent 42c593d
commit 4443223
Show file tree

Hide file tree

Showing 12 changed files with 53 additions and 30 deletions.
diff --git a/src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs b/src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs
@@ -322,7 +322,7 @@ public static MeterProvider Build(this MeterProviderBuilder meterProviderBuilder
     /// Sets the <see cref="ExemplarFilter"/> to be used for this provider.
     /// This is applied to all the metrics from this provider.
     /// </summary>
-    /// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+    /// <remarks><inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/></remarks>
     /// <param name="meterProviderBuilder"><see cref="MeterProviderBuilder"/>.</param>
     /// <param name="exemplarFilter"><see cref="ExemplarFilter"/> ExemplarFilter to use.</param>
     /// <returns>The supplied <see cref="MeterProviderBuilder"/> for chaining.</returns>

diff --git a/src/OpenTelemetry/Metrics/Exemplar/AlignedHistogramBucketExemplarReservoir.cs b/src/OpenTelemetry/Metrics/Exemplar/AlignedHistogramBucketExemplarReservoir.cs
@@ -6,8 +6,12 @@
 namespace OpenTelemetry.Metrics;
 
 /// <summary>
-/// The AlignedHistogramBucketExemplarReservoir implementation.
+/// AlignedHistogramBucketExemplarReservoir implementation.
 /// </summary>
+/// <remarks>
+/// Specification: <see
+/// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#alignedhistogrambucketexemplarreservoir"/>.
+/// </remarks>
 internal sealed class AlignedHistogramBucketExemplarReservoir : FixedSizeExemplarReservoir
 {
     public AlignedHistogramBucketExemplarReservoir(int numberOfBuckets)

diff --git a/src/OpenTelemetry/Metrics/Exemplar/AlwaysOffExemplarFilter.cs b/src/OpenTelemetry/Metrics/Exemplar/AlwaysOffExemplarFilter.cs
@@ -10,19 +10,19 @@ namespace OpenTelemetry.Metrics;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
-/// An ExemplarFilter which makes no measurements eligible for being an Exemplar.
-/// Using this ExemplarFilter is as good as disabling Exemplar feature.
+/// An <see cref="ExemplarFilter"/> implementation which makes no measurements
+/// eligible for becoming an <see cref="Exemplar"/>.
 /// </summary>
-/// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+/// <remarks>
+/// <inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/>
+/// Specification: <see
+/// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#alwaysoff"/>.
+/// </remarks>
 #if NET8_0_OR_GREATER
 [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
 public
 #else
-/// <summary>
-/// An ExemplarFilter which makes no measurements eligible for being an Exemplar.
-/// Using this ExemplarFilter is as good as disabling Exemplar feature.
-/// </summary>
 internal
 #endif
 sealed class AlwaysOffExemplarFilter : ExemplarFilter

diff --git a/src/OpenTelemetry/Metrics/Exemplar/AlwaysOnExemplarFilter.cs b/src/OpenTelemetry/Metrics/Exemplar/AlwaysOnExemplarFilter.cs
@@ -10,9 +10,14 @@ namespace OpenTelemetry.Metrics;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
-/// An ExemplarFilter which makes all measurements eligible for being an Exemplar.
+/// An <see cref="ExemplarFilter"/> implementation which makes all measurements
+/// eligible for becoming an <see cref="Exemplar"/>.
 /// </summary>
-/// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+/// <remarks>
+/// <inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/>
+/// Specification: <see
+/// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#alwayson"/>.
+/// </remarks>
 #if NET8_0_OR_GREATER
 [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif

diff --git a/src/OpenTelemetry/Metrics/Exemplar/Exemplar.cs b/src/OpenTelemetry/Metrics/Exemplar/Exemplar.cs
@@ -11,9 +11,13 @@ namespace OpenTelemetry.Metrics;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
-/// Represents an Exemplar data.
+/// Exemplar implementation.
 /// </summary>
-/// <remarks><b>WARNING</b>: This is an experimental API which might change or be removed in the future. Use at your own risk.</remarks>
+/// <remarks>
+/// <para experimental-warning="true"><b>WARNING</b>: This is an experimental API which might change or be removed in the future. Use at your own risk.</para>
+/// Specification: <see
+/// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplar"/>.
+/// </remarks>
 #if NET8_0_OR_GREATER
 [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif

diff --git a/src/OpenTelemetry/Metrics/Exemplar/ExemplarFilter.cs b/src/OpenTelemetry/Metrics/Exemplar/ExemplarFilter.cs
@@ -10,17 +10,18 @@ namespace OpenTelemetry.Metrics;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
-/// The base class for defining Exemplar Filter.
+/// ExemplarFilter base implementation and contract.
 /// </summary>
-/// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+/// <remarks>
+/// <inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/>
+/// Specification: <see
+/// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplarfilter"/>.
+/// </remarks>
 #if NET8_0_OR_GREATER
 [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
 public
 #else
-/// <summary>
-/// The base class for defining Exemplar Filter.
-/// </summary>
 internal
 #endif
     abstract class ExemplarFilter

diff --git a/src/OpenTelemetry/Metrics/Exemplar/ExemplarMeasurement.cs b/src/OpenTelemetry/Metrics/Exemplar/ExemplarMeasurement.cs
@@ -12,7 +12,7 @@ namespace OpenTelemetry.Metrics;
 /// <summary>
 /// Represents an Exemplar measurement.
 /// </summary>
-/// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+/// <remarks><inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/></remarks>
 /// <typeparam name="T">Measurement type.</typeparam>
 #if NET8_0_OR_GREATER
 [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]

diff --git a/src/OpenTelemetry/Metrics/Exemplar/ExemplarReservoir.cs b/src/OpenTelemetry/Metrics/Exemplar/ExemplarReservoir.cs
@@ -4,8 +4,12 @@
 namespace OpenTelemetry.Metrics;
 
 /// <summary>
-/// The base class for defining Exemplar Reservoir.
+/// ExemplarReservoir base implementation and contract.
 /// </summary>
+/// <remarks>
+/// Specification: <see
+/// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplarreservoir"/>.
+/// </remarks>
 internal abstract class ExemplarReservoir
 {
     /// <summary>

diff --git a/src/OpenTelemetry/Metrics/Exemplar/ReadOnlyExemplarCollection.cs b/src/OpenTelemetry/Metrics/Exemplar/ReadOnlyExemplarCollection.cs
@@ -13,7 +13,7 @@ namespace OpenTelemetry.Metrics;
 /// <summary>
 /// A read-only collection of <see cref="Exemplar" />s.
 /// </summary>
-/// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+/// <remarks><inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/></remarks>
 #if NET8_0_OR_GREATER
 [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif

diff --git a/src/OpenTelemetry/Metrics/Exemplar/SimpleFixedSizeExemplarReservoir.cs b/src/OpenTelemetry/Metrics/Exemplar/SimpleFixedSizeExemplarReservoir.cs
@@ -4,8 +4,12 @@
 namespace OpenTelemetry.Metrics;
 
 /// <summary>
-/// The SimpleFixedSizeExemplarReservoir implementation.
+/// SimpleFixedSizeExemplarReservoir implementation.
 /// </summary>
+/// <remarks>
+/// Specification: <see
+/// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#simplefixedsizeexemplarreservoir"/>.
+/// </remarks>
 internal sealed class SimpleFixedSizeExemplarReservoir : FixedSizeExemplarReservoir
 {
     private readonly Random random = new();

diff --git a/src/OpenTelemetry/Metrics/Exemplar/TraceBasedExemplarFilter.cs b/src/OpenTelemetry/Metrics/Exemplar/TraceBasedExemplarFilter.cs
@@ -12,19 +12,20 @@ namespace OpenTelemetry.Metrics;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
-/// An ExemplarFilter which makes those measurements eligible for being an Exemplar,
-/// which are recorded in the context of a sampled parent activity (span).
+/// An <see cref="ExemplarFilter"/> implementation which makes measurements
+/// recorded in the context of a sampled <see cref="Activity"/> (span) eligible
+/// for becoming an <see cref="Exemplar"/>.
 /// </summary>
-/// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+/// <remarks>
+/// <inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/>
+/// Specification: <see
+/// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#tracebased"/>.
+/// </remarks>
 #if NET8_0_OR_GREATER
 [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
 public
 #else
-/// <summary>
-/// An ExemplarFilter which makes those measurements eligible for being an Exemplar,
-/// which are recorded in the context of a sampled parent activity (span).
-/// </summary>
 internal
 #endif
     sealed class TraceBasedExemplarFilter : ExemplarFilter

diff --git a/src/OpenTelemetry/Metrics/MetricPoint.cs b/src/OpenTelemetry/Metrics/MetricPoint.cs
@@ -348,7 +348,7 @@ public readonly bool TryGetHistogramMinMaxValues(out double min, out double max)
     /// <summary>
     /// Gets the exemplars associated with the metric point.
     /// </summary>
-    /// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+    /// <remarks><inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/></remarks>
     /// <param name="exemplars"><see cref="ReadOnlyExemplarCollection"/>.</param>
     /// <returns><see langword="true" /> if exemplars exist; <see langword="false" /> otherwise.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]