API comments (#62)

* API comments

* stats APIs are documented

* tags API documentation

* 49 more files were modified. Build will fail as strict stylecop check is enabled

* one more

* few more comments

* fixed unit tests

* all done! =)

Author: SergeyKanzhelev

src/OpenCensus.Abstractions/Common/IClock.cs

@@ -16,10 +16,19 @@
 
 namespace OpenCensus.Common
 {
+    /// <summary>
+    /// Clock to get the current time with the nanoseconds precision.
+    /// </summary>
     public interface IClock
     {
+        /// <summary>
+        /// Gets the current instant from this clock as a timestamp.
+        /// </summary>
         ITimestamp Now { get; }
 
+        /// <summary>
+        /// Gets a time measurement with nanosecond precision that can only be used to calculate elapsed time.
+        /// </summary>
         long NowNanos { get; }
     }
 }

src/OpenCensus.Abstractions/Common/IDuration.cs

@@ -18,10 +18,19 @@ namespace OpenCensus.Common
 {
     using System;
 
+    /// <summary>
+    /// Represents duration with the nanoseconds precition.
+    /// </summary>
     public interface IDuration : IComparable<IDuration>
     {
+        /// <summary>
+        /// Gets the number of second in duration.
+        /// </summary>
         long Seconds { get; }
 
+        /// <summary>
+        /// Gets the number of nanoseconds in duration.
+        /// </summary>
         int Nanos { get; }
     }
 }

src/OpenCensus.Abstractions/Common/IScope.cs

@@ -18,6 +18,10 @@ namespace OpenCensus.Common
 {
     using System;
 
+    /// <summary>
+    /// Scope marker. Used as a syntactic sugar in methods like StartScopedSpan so it can be
+    /// wrapped in "using" block with automatic scope completion.
+    /// </summary>
     public interface IScope : IDisposable
     {
     }

src/OpenCensus.Abstractions/Common/ITimestamp.cs

@@ -18,16 +18,41 @@ namespace OpenCensus.Common
 {
     using System;
 
+    /// <summary>
+    /// Timestamp with the nanoseconds precision.
+    /// </summary>
     public interface ITimestamp : IComparable<ITimestamp>
     {
+        /// <summary>
+        /// Gets the number of seconds since the Unix Epoch represented by this timestamp.
+        /// </summary>
         long Seconds { get; }
 
+        /// <summary>
+        /// Gets the the number of nanoseconds after the number of seconds since the Unix Epoch represented
+        /// by this timestamp.
+        /// </summary>
         int Nanos { get; }
 
+        /// <summary>
+        /// Adds nanosToAdd nanosecond to the current timestamp.
+        /// </summary>
+        /// <param name="nanosToAdd">Number of nanoseconds to add.</param>
+        /// <returns>Returns the timstemp with added nanoseconds.</returns>
         ITimestamp AddNanos(long nanosToAdd);
 
+        /// <summary>
+        /// Adds duration to the timestamp.
+        /// </summary>
+        /// <param name="duration">Duration to add to the timestamp.</param>
+        /// <returns>Returns the timestamp with added duration.</returns>
         ITimestamp AddDuration(IDuration duration);
 
+        /// <summary>
+        /// Substructs timestamp from the current timestamp. Typically to calculate duration.
+        /// </summary>
+        /// <param name="timestamp">Timestamp to substruct.</param>
+        /// <returns>Returns the timestamp with the substructed duration.</returns>
         IDuration SubtractTimestamp(ITimestamp timestamp);
     }
 }

src/OpenCensus.Abstractions/Internal/IEventQueue.cs

@@ -16,8 +16,15 @@
 
 namespace OpenCensus.Internal
 {
+    /// <summary>
+    /// Event queue abstraction.
+    /// </summary>
     public interface IEventQueue
     {
+        /// <summary>
+        /// Queues a single entry.
+        /// </summary>
+        /// <param name="entry">Entry to be queued.</param>
         void Enqueue(IEventQueueEntry entry);
     }
 }

src/OpenCensus.Abstractions/Internal/IEventQueueEntry.cs

@@ -16,8 +16,14 @@
 
 namespace OpenCensus.Internal
 {
+    /// <summary>
+    /// Queue entry abstraction.
+    /// </summary>
     public interface IEventQueueEntry
     {
+        /// <summary>
+        /// Method process will be called when queue entry needs to be processed.
+        /// </summary>
         void Process();
     }
 }

src/OpenCensus.Abstractions/Internal/ITimestampConverter.cs

@@ -18,8 +18,16 @@ namespace OpenCensus.Internal
 {
     using OpenCensus.Common;
 
+    /// <summary>
+    /// Converts nanoseconds into timestamp.
+    /// </summary>
     public interface ITimestampConverter
     {
+        /// <summary>
+        /// Converts nanoseconds to the timestamp.
+        /// </summary>
+        /// <param name="nanoTime">Nanoseconds time.</param>
+        /// <returns>Timestamp from the nanoseconds.</returns>
         ITimestamp ConvertNanoTime(long nanoTime);
     }
 }

src/OpenCensus.Abstractions/OpenCensus.Abstractions.csproj

@@ -14,7 +14,7 @@
     <RootNamespace>OpenCensus</RootNamespace>
   </PropertyGroup>
   <PropertyGroup>
-    <CodeAnalysisRuleSet>$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildProjectDirectory), 'OpenCensus.sln'))/build/OpenCensus.prod.loose.ruleset</CodeAnalysisRuleSet>
+    <CodeAnalysisRuleSet>$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildProjectDirectory), 'OpenCensus.sln'))/build/OpenCensus.prod.ruleset</CodeAnalysisRuleSet>
   </PropertyGroup>
   <PropertyGroup Condition="'$(Configuration)'=='Debug'">
     <DebugType>full</DebugType>

src/OpenCensus.Abstractions/Stats/Aggregations/ICount.cs

@@ -16,6 +16,9 @@
 
 namespace OpenCensus.Stats.Aggregations
 {
+    /// <summary>
+    /// Count aggregation.
+    /// </summary>
     public interface ICount : IAggregation
     {
     }

src/OpenCensus.Abstractions/Stats/Aggregations/ICountData.cs

@@ -16,8 +16,14 @@
 
 namespace OpenCensus.Stats.Aggregations
 {
+    /// <summary>
+    /// Data accumulated by Count aggregation.
+    /// </summary>
     public interface ICountData : IAggregationData
     {
+        /// <summary>
+        /// Gets the counter representing the result of an aggregation.
+        /// </summary>
         long Count { get; }
     }
 }