Add source code annotations (#5)

* docs: add annotations to count data cooker

* docs: add annotations to telemetry data cooker

* docs: add annotations to timeline data cooker

* docs: add annotations to events

* docs: add annotations to tables

* docs: add source parser and processing source annotations

Author: Alaaeddine-chakroun

.gitignore

@@ -37,3 +37,5 @@ msbuild.wrn
 .vs/
 TestResult.xml
 
+# Documentation
+docs

WPAPlugin/Constants/WperfPluginConstants.cs

@@ -35,21 +35,63 @@ namespace WPAPlugin.Constants
     public static class WperfPluginConstants
     {
         // Event Identifiers used by Data cookers
+
+        /// <summary>
+        /// Constant added to counting events parsed from a single count .json input file.
+        /// </summary>
         public const string PerformanceCounterEventKey = "PerformanceCounterEvent";
+
+        /// <summary>
+        ///  WperfPluginConstants.PerformanceCounterTimelineEventKey: constant added to counting events parsed from a timeline count .json input file.
+        /// </summary>
         public const string PerformanceCounterTimelineEventKey = "PerformanceCounterTimelineEvent";
+
+        /// <summary>
+        /// Constant added to telemetry events parsed from a timeline .json input file.
+        /// </summary>
         public const string TelemetryEventKey = "TelemetryEvent";
 
         // Parser ID (There should be no reason to have multiple parsers as of now)
+
+        /// <summary>
+        /// Constant string identifier of WperfSourceParser
+        /// </summary>
         public const string ParserId = "WperfSourceParser";
 
         // Cooker IDs
+
+        /// <summary>
+        /// Constant string identifier of WperfTimelineDataCooker
+        /// </summary>
         public const string TimelineCookerId = "WperfDataCooker";
+
+        /// <summary>
+        /// Constant string identifier of WperfCountDataCooker
+        /// </summary>
         public const string CountCookerId = "WperfCountDataCooker";
+
+        /// <summary>
+        /// Constant string identifier of WperfTelemetryDataCooker
+        /// </summary>
         public const string TelemetryCookerId = "WperfTelemetryCooker";
 
-        public static readonly string[] WperfPresetMetrics = { "MPKI", "per TLB access", "per branch", "per cache access", "per cycle", "percent of cycles", "percent of operations", "percent of slots" };
+        public static readonly string[] WperfPresetMetrics =
+        {
+            "MPKI",
+            "per TLB access",
+            "per branch",
+            "per cache access",
+            "per cycle",
+            "percent of cycles",
+            "percent of operations",
+            "percent of slots"
+        };
 
         // Cooker Paths
+        /// <summary>
+        /// In order for the events processd by the DataCooker to be consumed by the tables, each DataCooker requires declaring a path that maps itself with the appropriate DataSource.
+        /// </summary>
+
         public static readonly DataCookerPath CookerPath = DataCookerPath.ForSource(
             ParserId,
             TimelineCookerId

WPAPlugin/DataCookers/WperfCountDataCooker.cs

@@ -28,22 +28,35 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.Threading;
 using Microsoft.Performance.SDK;
 using Microsoft.Performance.SDK.Extensibility;
 using Microsoft.Performance.SDK.Extensibility.DataCooking;
 using Microsoft.Performance.SDK.Extensibility.DataCooking.SourceDataCooking;
-using System.Collections.Generic;
-using System.Collections.ObjectModel;
-using System.Threading;
 using WPAPlugin.Constants;
 using WPAPlugin.Events;
 
 namespace WPAPlugin.DataCookers
 {
+    /// <summary>
+    /// WperfCountDataCooker is a SourceDataCooker that passes the counting WperfEvents as is.
+    /// </summary>
     public class WperfCountDataCooker : SourceDataCooker<WperfEvent, WperfSourceParser, string>
     {
         private readonly List<WperfEvent> wperfEvents;
 
+        /// <summary>
+        /// Data processed by the DataCooker needs to be stored in a field annotated with DataOutput
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// private readonly List<WperfEvent> wperfEvents;
+        /// [DataOutput]
+        /// public IReadOnlyList<WperfEvent> WperfEvents { get; }
+        /// </code>
+        /// </example>
         [DataOutput]
         public IReadOnlyList<WperfEvent> WperfEvents { get; }
 
@@ -56,6 +69,21 @@ public WperfCountDataCooker()
 
         public override string Description => "Passes on the counting data as is";
 
+        /// <summary>
+        /// WperfCountDataCooker filters the counting events from all the processed WperfEvents by the WperfSourceParser through the DataKeys field.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// public override ReadOnlyHashSet<string> DataKeys =>
+        ///    new ReadOnlyHashSet<string>(
+        ///        new HashSet<string>
+        ///        {
+        ///            WperfPluginConstants.PerformanceCounterEventKey,
+        ///            WperfPluginConstants.PerformanceCounterTimelineEventKey
+        ///        }
+        ///    );
+        /// </code>
+        /// </example>
         public override ReadOnlyHashSet<string> DataKeys =>
             new ReadOnlyHashSet<string>(
                 new HashSet<string>
@@ -65,6 +93,24 @@ public WperfCountDataCooker()
                 }
             );
 
+        /// <summary>
+        /// Data processing happens at the CookDataElement level that takes the data marked as ready to be processed from the SourceParser, as well as the WperfSourceParser instance to extract context if needed.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// public override DataProcessingResult CookDataElement(
+        ///    WperfEvent data,
+        ///    WperfSourceParser context,
+        ///    CancellationToken cancellationToken
+        ///)
+        ///{
+        ///    ... // process data and add to the field annotated with [DataOutput]
+        ///    wperfEvents.Add(cookedData);
+        ///
+        ///    return DataProcessingResult.Processed;
+        ///}
+        /// </code>
+        /// </example>
         public override DataProcessingResult CookDataElement(
             WperfEvent data,
             WperfSourceParser context,

WPAPlugin/DataCookers/WperfTelemetryDataCooker.cs

@@ -28,23 +28,35 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.Threading;
 using Microsoft.Performance.SDK;
 using Microsoft.Performance.SDK.Extensibility;
 using Microsoft.Performance.SDK.Extensibility.DataCooking;
 using Microsoft.Performance.SDK.Extensibility.DataCooking.SourceDataCooking;
-using System.Collections.Generic;
-using System.Collections.ObjectModel;
-using System.Threading;
 using WPAPlugin.Constants;
 using WPAPlugin.Events;
 
 namespace WPAPlugin.DataCookers
 {
-    public class WperfTelemetryDataCooker
-        : SourceDataCooker<WperfEvent, WperfSourceParser, string>
+    /// <summary>
+    /// WperfTelemetryDataCooker is a SourceDataCooker that adds the relative start and end time to the counting WperfEvents.
+    /// </summary>
+    public class WperfTelemetryDataCooker : SourceDataCooker<WperfEvent, WperfSourceParser, string>
     {
         private readonly List<WperfEventWithRelativeTimestamp> wperfEventWithRelativeTimestamps;
 
+        /// <summary>
+        /// Data processed by the DataCooker needs to be stored in a field annotated with DataOutput
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// private readonly List<WperfEventWithRelativeTimestamp> wperfEventWithRelativeTimestamps;
+        /// [DataOutput]
+        /// public IReadOnlyList<WperfEventWithRelativeTimestamp> WperfEventWithRelativeTimestamps { get; }
+        /// </code>
+        /// </example>
         [DataOutput]
         public IReadOnlyList<WperfEventWithRelativeTimestamp> WperfEventWithRelativeTimestamps { get; }
 
@@ -60,11 +72,40 @@ public WperfTelemetryDataCooker()
 
         public override string Description => "Adds relative timestamps to telemetry events";
 
+        /// <summary>
+        /// WperfTimelineDataCooker filters the telemetry events from all the processed WperfEvents by the WperfSourceParser through the DataKeys field.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// public override ReadOnlyHashSet<string> DataKeys =>
+        ///    new ReadOnlyHashSet<string>(
+        ///        new HashSet<string> { WperfPluginConstants.TelemetryEventKey }
+        ///    );
+        /// </code>
+        /// </example>
         public override ReadOnlyHashSet<string> DataKeys =>
             new ReadOnlyHashSet<string>(
                 new HashSet<string> { WperfPluginConstants.TelemetryEventKey }
             );
 
+        /// <summary>
+        /// Data processing happens at the CookDataElement level that takes the data marked as ready to be processed from the SourceParser, as well as the WperfSourceParser instance to extract context if needed.
+        /// </summary>
+        /// <example>
+        /// <code>
+        ///     public override DataProcessingResult CookDataElement(
+        ///     WperfEvent data,
+        ///     WperfSourceParser context,
+        ///     CancellationToken cancellationToken
+        /// )
+        /// {
+        ///     ... // process data and add to the field annotated with [DataOutput]
+        ///     wperfEventWithRelativeTimestamps.Add(cookedEvent);
+        ///
+        ///     return DataProcessingResult.Processed;
+        /// }
+        /// </code>
+        /// </example>
         public override DataProcessingResult CookDataElement(
             WperfEvent data,
             WperfSourceParser context,

WPAPlugin/DataCookers/WperfTimelineDataCooker.cs

@@ -28,23 +28,36 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.Threading;
 using Microsoft.Performance.SDK;
 using Microsoft.Performance.SDK.Extensibility;
 using Microsoft.Performance.SDK.Extensibility.DataCooking;
 using Microsoft.Performance.SDK.Extensibility.DataCooking.SourceDataCooking;
-using System.Collections.Generic;
-using System.Collections.ObjectModel;
-using System.Threading;
 using WPAPlugin.Constants;
 using WPAPlugin.Events;
 
 namespace WPAPlugin.DataCookers
 {
-    public class WperfTimelineDataCooker
-        : SourceDataCooker<WperfEvent, WperfSourceParser, string>
+    /// <summary>
+    /// WperfCountDataCooker is a SourceDataCooker that adds the relative start and end time to the counting WperfEvents.
+    /// </summary>
+    public class WperfTimelineDataCooker : SourceDataCooker<WperfEvent, WperfSourceParser, string>
     {
         private readonly List<WperfEventWithRelativeTimestamp> wperfEventWithRelativeTimestamps;
 
+        /// <summary>
+        /// Data processed by the DataCooker needs to be stored in a field annotated with DataOutput
+        /// </summary>
+        /// <example>
+        /// <code>
+        ///     private readonly List<WperfEventWithRelativeTimestamp> wperfEventWithRelativeTimestamps;
+        ///
+        ///     [DataOutput]
+        ///     public IReadOnlyList<WperfEventWithRelativeTimestamp> WperfEventWithRelativeTimestamps { get; }
+        /// </code>
+        /// </example>
         [DataOutput]
         public IReadOnlyList<WperfEventWithRelativeTimestamp> WperfEventWithRelativeTimestamps { get; }
 
@@ -60,11 +73,43 @@ public WperfTimelineDataCooker()
 
         public override string Description => "Adds relative timestamps to counting events";
 
+        /// <summary>
+        /// WperfTimelineDataCooker filters the counting events from all the processed WperfEvents by the WperfSourceParser through the DataKeys field.
+        /// </summary>
+        /// <example>
+        /// <code>
+        ///    public override ReadOnlyHashSet<string> DataKeys =>
+        ///     new ReadOnlyHashSet<string>(
+        ///         new HashSet<string>
+        ///         {
+        ///             WperfPluginConstants.PerformanceCounterTimelineEventKey
+        ///         }
+        ///     );
+        /// </code>
+        /// </example>
         public override ReadOnlyHashSet<string> DataKeys =>
             new ReadOnlyHashSet<string>(
                 new HashSet<string> { WperfPluginConstants.PerformanceCounterTimelineEventKey }
             );
 
+        /// <summary>
+        /// Data processing happens at the CookDataElement level that takes the data marked as ready to be processed from the SourceParser, as well as the WperfSourceParser instance to extract context if needed.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// public override DataProcessingResult CookDataElement(
+        ///     WperfEvent data,
+        ///     WperfSourceParser context,
+        ///     CancellationToken cancellationToken
+        /// )
+        /// {
+        ///     ... // process data and add to the field annotated with [DataOutput]
+        ///     wperfEventWithRelativeTimestamps.Add(cookedEvent);
+        ///
+        ///     return DataProcessingResult.Processed;
+        /// }
+        /// </code>
+        /// </example>
         public override DataProcessingResult CookDataElement(
             WperfEvent data,
             WperfSourceParser context,

WPAPlugin/Events/WperfEvent.cs

@@ -32,24 +32,68 @@
 
 namespace WPAPlugin.Events
 {
+    /// <summary>
+    /// WperfEvent is a class that stores WindowsPerf events.
+    /// In order to keep the plugin structure straight forward and not resorting to multiple
+    /// SourceParsers, counting events and timeline events are stored in WperfEvent instances
+    /// by sharing their common properties and ignoring unrelated fields.
+    /// </summary>
     public class WperfEvent : IKeyedDataType<string>
     {
         // Common fields
+
+        /// <summary>
+        /// int representing the core number of said event.
+        /// </summary>
         public int CoreNumber { get; set; }
+
+        /// <summary>
+        /// double represeting the value of the count/telemetry.
+        /// </summary>
         public double Value { get; set; }
+
+        /// <summary>
+        /// string representing name of the event/metric.
+        /// </summary>
         public string Name { get; set; }
+
+        /// <summary>
+        /// double representing the start time of the event.
+        /// </summary>
         public double StartTime { get; set; }
+
+        /// <summary>
+        /// double representing the end time of the event.
+        /// </summary>
         public double EndTime { get; set; }
+
+        /// <summary>
+        /// string used in filtering the events by the DataCookers.
+        /// </summary>
         public string Key { get; set; }
 
         // Counting fields
+        /// <summary>
+        /// string representing the counting event index.
+        /// </summary>
         public string Index { get; set; }
+
+        /// <summary>
+        /// string representing the counting event note.
+        /// </summary>
         public string Note { get; set; }
 
         // Telemetry Fields
+
+        /// <summary>
+        /// string representing the metric unit.
+        /// </summary>
         public string Unit { get; set; }
-        public string ProductName { get; set; }
 
+        /// <summary>
+        /// string representing the metric product name.
+        /// </summary>
+        public string ProductName { get; set; }
 
         public WperfEvent() { }