Adding XML comments - part 01 (#955)

* enabling cs1591 for OT project

Adding some xml comments - 1

Adding some xml comments - 2

changing some references to semantic

updating returns message from aggregator

Adding more comments

Adding dispose comments

undoing some changes

commenting rule

uncomment rule

* renaming from isdisposing to disposing

* updating comments

* cijo's comments

* updating texts

Co-authored-by: Cijo Thomas <cithomas@microsoft.com>

src/OpenTelemetry/Context/Propagation/DistributedContextBinarySerializerBase.cs

@@ -16,6 +16,9 @@
 
 namespace OpenTelemetry.Context.Propagation
 {
+    /// <summary>
+    /// DistributedContextBinarySerializerBase base class.
+    /// </summary>
     public abstract class DistributedContextBinarySerializerBase
     {
         /// <summary>

src/OpenTelemetry/Instrumentation/DiagnosticSourceSubscriber.cs

@@ -81,6 +81,7 @@ namespace OpenTelemetry.Instrumentation
         {
         }
 
+        /// <inheritdoc/>
         public void Dispose()
         {
             if (Interlocked.CompareExchange(ref this.disposed, 1, 0) == 1)

src/OpenTelemetry/Instrumentation/ListenerHandler.cs

@@ -17,29 +17,63 @@ using System.Diagnostics;
 
 namespace OpenTelemetry.Instrumentation
 {
+    /// <summary>
+    /// ListenerHandler base class.
+    /// </summary>
     public abstract class ListenerHandler
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ListenerHandler"/> class.
+        /// </summary>
+        /// <param name="sourceName">The name of the <see cref="ListenerHandler"/>.</param>
         public ListenerHandler(string sourceName)
         {
             this.SourceName = sourceName;
         }
 
+        /// <summary>
+        /// Gets the name of the <see cref="ListenerHandler"/>.
+        /// </summary>
         public string SourceName { get; }
 
+        /// <summary>
+        /// Gets a value indicating whether the <see cref="ListenerHandler"/> supports NULL <see cref="Activity"/>.
+        /// </summary>
         public virtual bool SupportsNullActivity { get; } = false;
 
+        /// <summary>
+        /// Method called for an event with the suffix 'Start'.
+        /// </summary>
+        /// <param name="activity">The <see cref="Activity"/> to be started.</param>
+        /// <param name="payload">An object that represent the value being passed as a payload for the event.</param>
         public virtual void OnStartActivity(Activity activity, object payload)
         {
         }
 
+        /// <summary>
+        /// Method called for an event with the suffix 'Stop'.
+        /// </summary>
+        /// <param name="activity">The <see cref="Activity"/> to be stopped.</param>
+        /// <param name="payload">An object that represent the value being passed as a payload for the event.</param>
         public virtual void OnStopActivity(Activity activity, object payload)
         {
         }
 
+        /// <summary>
+        /// Method called for an event with the suffix 'Exception'.
+        /// </summary>
+        /// <param name="activity">The <see cref="Activity"/>.</param>
+        /// <param name="payload">An object that represent the value being passed as a payload for the event.</param>
         public virtual void OnException(Activity activity, object payload)
         {
         }
 
+        /// <summary>
+        /// Method called for an event which does not have 'Start', 'Stop' or 'Exception' as suffix.
+        /// </summary>
+        /// <param name="name">Custom name.</param>
+        /// <param name="activity">The <see cref="Activity"/> to be processed.</param>
+        /// <param name="payload">An object that represent the value being passed as a payload for the event.</param>
         public virtual void OnCustom(string name, Activity activity, object payload)
         {
         }

src/OpenTelemetry/Metrics/Aggregators/Aggregator.cs

@@ -18,15 +18,34 @@ using OpenTelemetry.Metrics.Export;
 
 namespace OpenTelemetry.Metrics.Aggregators
 {
+    /// <summary>
+    /// Aggregator base class.
+    /// </summary>
+    /// <typeparam name="T">The type.</typeparam>
     public abstract class Aggregator<T>
         where T : struct
     {
+        /// <summary>
+        /// Adds value to the running total in a thread safe manner.
+        /// </summary>
+        /// <param name="value">Value to be aggregated.</param>
         public abstract void Update(T value);
 
+        /// <summary>
+        /// Checkpoints the current aggregate data, and resets the state.
+        /// </summary>
         public abstract void Checkpoint();
 
+        /// <summary>
+        /// Convert Aggregator data to MetricData.
+        /// </summary>
+        /// <returns>An instance of <see cref="MetricData"/> representing the currently aggregated value.</returns>
         public abstract MetricData ToMetricData();
 
+        /// <summary>
+        /// Get Aggregation Type.
+        /// </summary>
+        /// <returns><see cref="AggregationType"/>.</returns>
         public abstract AggregationType GetAggregationType();
     }
 }

src/OpenTelemetry/Metrics/Aggregators/DoubleCounterSumAggregator.cs

@@ -28,12 +28,14 @@ namespace OpenTelemetry.Metrics.Aggregators
         private double sum;
         private double checkPoint;
 
+        /// <inheritdoc/>
         public override void Checkpoint()
         {
             // checkpoints the current running sum into checkpoint, and starts counting again.
             this.checkPoint = Interlocked.Exchange(ref this.sum, 0.0);
         }
 
+        /// <inheritdoc/>
         public override MetricData ToMetricData()
         {
             return new DoubleSumData
@@ -43,11 +45,13 @@ namespace OpenTelemetry.Metrics.Aggregators
             };
         }
 
+        /// <inheritdoc/>
         public override AggregationType GetAggregationType()
         {
             return AggregationType.DoubleSum;
         }
 
+        /// <inheritdoc/>
         public override void Update(double value)
         {
             // Adds value to the running total in a thread safe manner.

src/OpenTelemetry/Metrics/Aggregators/DoubleLastValueAggregator.cs

@@ -28,11 +28,13 @@ namespace OpenTelemetry.Metrics.Aggregators
         private double value;
         private double checkpoint;
 
+        /// <inheritdoc/>
         public override void Checkpoint()
         {
             Interlocked.Exchange(ref this.checkpoint, this.value);
         }
 
+        /// <inheritdoc/>
         public override MetricData ToMetricData()
         {
             return new DoubleSumData
@@ -42,11 +44,13 @@ namespace OpenTelemetry.Metrics.Aggregators
             };
         }
 
+        /// <inheritdoc/>
         public override AggregationType GetAggregationType()
         {
             return AggregationType.DoubleSum;
         }
 
+        /// <inheritdoc/>
         public override void Update(double newValue)
         {
             Interlocked.Exchange(ref this.value, newValue);

src/OpenTelemetry/Metrics/Aggregators/DoubleMeasureMinMaxSumCountAggregator.cs

@@ -29,16 +29,19 @@ namespace OpenTelemetry.Metrics.Aggregators
         private DoubleSummary checkPoint = new DoubleSummary();
         private object updateLock = new object();
 
+        /// <inheritdoc/>
         public override void Checkpoint()
         {
             this.checkPoint = Interlocked.Exchange(ref this.summary, new DoubleSummary());
         }
 
+        /// <inheritdoc/>
         public override AggregationType GetAggregationType()
         {
             return AggregationType.DoubleSummary;
         }
 
+        /// <inheritdoc/>
         public override MetricData ToMetricData()
         {
             return new DoubleSummaryData
@@ -51,6 +54,7 @@ namespace OpenTelemetry.Metrics.Aggregators
             };
         }
 
+        /// <inheritdoc/>
         public override void Update(double value)
         {
             lock (this.updateLock)

src/OpenTelemetry/Metrics/Aggregators/Int64CounterSumAggregator.cs

@@ -28,12 +28,14 @@ namespace OpenTelemetry.Metrics.Aggregators
         private long sum;
         private long checkPoint;
 
+        /// <inheritdoc/>
         public override void Checkpoint()
         {
             // checkpoints the current running sum into checkpoint, and starts counting again.
             this.checkPoint = Interlocked.Exchange(ref this.sum, 0);
         }
 
+        /// <inheritdoc/>
         public override MetricData ToMetricData()
         {
             return new Int64SumData
@@ -43,11 +45,13 @@ namespace OpenTelemetry.Metrics.Aggregators
             };
         }
 
+        /// <inheritdoc/>
         public override AggregationType GetAggregationType()
         {
             return AggregationType.LongSum;
         }
 
+        /// <inheritdoc/>
         public override void Update(long value)
         {
             // Adds value to the running total in a thread safe manner.

src/OpenTelemetry/Metrics/Aggregators/Int64LastValueAggregator.cs

@@ -28,11 +28,13 @@ namespace OpenTelemetry.Metrics.Aggregators
         private long value;
         private long checkpoint;
 
+        /// <inheritdoc/>
         public override void Checkpoint()
         {
             Interlocked.Exchange(ref this.checkpoint, this.value);
         }
 
+        /// <inheritdoc/>
         public override MetricData ToMetricData()
         {
             return new Int64SumData
@@ -42,11 +44,13 @@ namespace OpenTelemetry.Metrics.Aggregators
             };
         }
 
+        /// <inheritdoc/>
         public override AggregationType GetAggregationType()
         {
             return AggregationType.LongSum;
         }
 
+        /// <inheritdoc/>
         public override void Update(long newValue)
         {
             Interlocked.Exchange(ref this.value, newValue);

src/OpenTelemetry/Metrics/Aggregators/Int64MeasureMinMaxSumCountAggregator.cs

@@ -29,16 +29,19 @@ namespace OpenTelemetry.Metrics.Aggregators
         private LongSummary checkPoint = new LongSummary();
         private object updateLock = new object();
 
+        /// <inheritdoc/>
         public override void Checkpoint()
         {
             this.checkPoint = Interlocked.Exchange(ref this.summary, new LongSummary());
         }
 
+        /// <inheritdoc/>
         public override AggregationType GetAggregationType()
         {
             return AggregationType.Int64Summary;
         }
 
+        /// <inheritdoc/>
         public override MetricData ToMetricData()
         {
             return new Int64SummaryData
@@ -51,6 +54,7 @@ namespace OpenTelemetry.Metrics.Aggregators
             };
         }
 
+        /// <inheritdoc/>
         public override void Update(long value)
         {
             lock (this.updateLock)

src/OpenTelemetry/Metrics/Export/MetricData.cs

@@ -19,6 +19,9 @@ using System.Collections.Generic;
 
 namespace OpenTelemetry.Metrics.Export
 {
+    /// <summary>
+    /// MetricData base class.
+    /// </summary>
     public abstract class MetricData
     {
         public DateTime Timestamp { get; set; }

src/OpenTelemetry/Metrics/Export/MetricExporter.cs

@@ -20,8 +20,14 @@ using System.Threading.Tasks;
 
 namespace OpenTelemetry.Metrics.Export
 {
+    /// <summary>
+    /// MetricExporter base class.
+    /// </summary>
     public abstract class MetricExporter
     {
+        /// <summary>
+        /// Enumeration used to define the result of an export operation.
+        /// </summary>
         public enum ExportResult
         {
             /// <summary>
@@ -40,6 +46,12 @@ namespace OpenTelemetry.Metrics.Export
             FailedRetryable = 2,
         }
 
+        /// <summary>
+        /// Exports batch of metrics asynchronously.
+        /// </summary>
+        /// <param name="metrics">Batch of metrics to export.</param>
+        /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>Result of export.</returns>
         public abstract Task<ExportResult> ExportAsync(IEnumerable<Metric> metrics, CancellationToken cancellationToken);
     }
 }

src/OpenTelemetry/Metrics/Export/MetricProcessor.cs

@@ -18,6 +18,9 @@ using System.Collections.Generic;
 
 namespace OpenTelemetry.Metrics.Export
 {
+    /// <summary>
+    /// MetricProcessor base class.
+    /// </summary>
     public abstract class MetricProcessor
     {
         /// <summary>

src/OpenTelemetry/Metrics/Export/UngroupedBatcher.cs

@@ -34,6 +34,7 @@ namespace OpenTelemetry.Metrics.Export
             this.metrics = new List<Metric>();
         }
 
+        /// <inheritdoc/>
         public override void FinishCollectionCycle(out IEnumerable<Metric> metrics)
         {
             // The batcher is currently stateless. i.e it forgets state after collection is done.
@@ -44,6 +45,7 @@ namespace OpenTelemetry.Metrics.Export
             OpenTelemetrySdkEventSource.Log.BatcherCollectionCompleted(this.metrics.Count);
         }
 
+        /// <inheritdoc/>
         public override void Process(Metric metric)
         {
             this.metrics.Add(metric);

src/OpenTelemetry/OpenTelemetry.csproj

@@ -4,7 +4,7 @@
     <Description>OpenTelemetry .NET SDK</Description>
   </PropertyGroup>
 
-   <!--
+  <!--
   Uncomment for development. This will disable the verification that every public method needs to be documented.
   //TODO: Disable this exception, and actually do document all public API. Quite a lot are missing now.
   -->

src/OpenTelemetry/Trace/ActivityExporter.cs

@@ -62,12 +62,17 @@ namespace OpenTelemetry.Trace
         /// <returns>Returns <see cref="Task"/>.</returns>
         public abstract Task ShutdownAsync(CancellationToken cancellationToken);
 
+        /// <inheritdoc/>
         public void Dispose()
         {
             this.Dispose(true);
             GC.SuppressFinalize(this);
         }
 
+        /// <summary>
+        /// Releases the unmanaged resources used by this class and optionally releases the managed resources.
+        /// </summary>
+        /// <param name="disposing"><see langword="true"/> to release both managed and unmanaged resources; <see langword="false"/> to release only unmanaged resources.</param>
         protected virtual void Dispose(bool disposing)
         {
         }

src/OpenTelemetry/Trace/ActivitySourceAdapter.cs

@@ -30,9 +30,9 @@ namespace OpenTelemetry.Trace
     /// </summary>
     public class ActivitySourceAdapter
     {
-        private Sampler sampler;
-        private ActivityProcessor activityProcessor;
-        private Resource resource;
+        private readonly Sampler sampler;
+        private readonly ActivityProcessor activityProcessor;
+        private readonly Resource resource;
 
         internal ActivitySourceAdapter(Sampler sampler, ActivityProcessor activityProcessor, Resource resource)
         {
@@ -45,6 +45,10 @@ namespace OpenTelemetry.Trace
         {
         }
 
+        /// <summary>
+        /// Method that starts an <see cref="Activity"/>.
+        /// </summary>
+        /// <param name="activity"><see cref="Activity"/> to be started.</param>
         public void Start(Activity activity)
         {
             this.RunGetRequestedData(activity);
@@ -55,6 +59,10 @@ namespace OpenTelemetry.Trace
             }
         }
 
+        /// <summary>
+        /// Method that stops an <see cref="Activity"/>.
+        /// </summary>
+        /// <param name="activity"><see cref="Activity"/> to be stopped.</param>
         public void Stop(Activity activity)
         {
             if (activity.IsAllDataRequested)

src/OpenTelemetry/Trace/BatchingActivityProcessor.cs

@@ -208,7 +208,11 @@ namespace OpenTelemetry.Trace
             this.Dispose(true);
         }
 
-        protected virtual void Dispose(bool isDisposing)
+        /// <summary>
+        /// Releases the unmanaged resources used by this class and optionally releases the managed resources.
+        /// </summary>
+        /// <param name="disposing"><see langword="true"/> to release both managed and unmanaged resources; <see langword="false"/> to release only unmanaged resources.</param>
+        protected virtual void Dispose(bool disposing)
         {
             try
             {
@@ -219,7 +223,7 @@ namespace OpenTelemetry.Trace
                 OpenTelemetrySdkEventSource.Log.SpanProcessorException(nameof(this.Dispose), ex);
             }
 
-            if (isDisposing && !this.isDisposed)
+            if (disposing && !this.isDisposed)
             {
                 if (this.exporter is IDisposable disposableExporter)
                 {

src/OpenTelemetry/Trace/Internal/BroadcastActivityProcessor.cs

@@ -101,7 +101,7 @@ namespace OpenTelemetry.Trace.Internal
             this.Dispose(true);
         }
 
-        protected virtual void Dispose(bool isDisposing)
+        protected virtual void Dispose(bool disposing)
         {
             try
             {
@@ -112,7 +112,7 @@ namespace OpenTelemetry.Trace.Internal
                 OpenTelemetrySdkEventSource.Log.SpanProcessorException(nameof(this.Dispose), ex);
             }
 
-            if (isDisposing && !this.isDisposed)
+            if (disposing && !this.isDisposed)
             {
                 foreach (var processor in this.processors)
                 {

src/OpenTelemetry/Trace/SimpleActivityProcessor.cs

@@ -91,7 +91,11 @@ namespace OpenTelemetry.Trace
             this.Dispose(true);
         }
 
-        protected virtual void Dispose(bool isDisposing)
+        /// <summary>
+        /// Releases the unmanaged resources used by this class and optionally releases the managed resources.
+        /// </summary>
+        /// <param name="disposing"><see langword="true"/> to release both managed and unmanaged resources; <see langword="false"/> to release only unmanaged resources.</param>
+        protected virtual void Dispose(bool disposing)
         {
             try
             {
@@ -102,7 +106,7 @@ namespace OpenTelemetry.Trace
                 OpenTelemetrySdkEventSource.Log.SpanProcessorException(nameof(this.Dispose), ex);
             }
 
-            if (isDisposing)
+            if (disposing)
             {
                 if (this.exporter is IDisposable disposableExporter)
                 {