From 7dba67b0cecddc3420ee97c17779572865e8cd4c Mon Sep 17 00:00:00 2001
From: Jared Parsons <jared@paranoidcoding.org>
Date: Sat, 8 Jun 2024 10:01:56 -0700
Subject: [PATCH] doc update (#137)

---
 .vscode/launch.json                         |  2 +-
 src/Basic.CompilerLog.Util/BinaryLogUtil.cs | 20 ++++++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/.vscode/launch.json b/.vscode/launch.json
index 772f551..1ab0cb9 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -12,7 +12,7 @@
             // If you have changed target frameworks, make sure to update the program path.
             "program": "${workspaceFolder}/artifacts/bin/Basic.CompilerLog/debug_net7.0/Basic.CompilerLog.dll",
             "args": ["print", ".\\msbuild.binlog" ],
-            "cwd": "c:\\Users\\jaredpar\\temp\\console",
+            "cwd": "e:\\temp\\console",
             // "cwd": "${workspaceFolder}/src/Basic.CompilerLog",
             // For more information about the 'console' field, see https://aka.ms/VSCode-CS-LaunchJson-Console
             "console": "internalConsole",
diff --git a/src/Basic.CompilerLog.Util/BinaryLogUtil.cs b/src/Basic.CompilerLog.Util/BinaryLogUtil.cs
index 6f29d0f..5694df4 100644
--- a/src/Basic.CompilerLog.Util/BinaryLogUtil.cs
+++ b/src/Basic.CompilerLog.Util/BinaryLogUtil.cs
@@ -13,6 +13,25 @@ namespace Basic.CompilerLog.Util;
 
 public static class BinaryLogUtil
 {
+    // My understanding of the ids in the BuildEventContext type is:
+    //
+    // 1. Every project evaluation will have a unique evaluation id. Many evaluations of the same
+    //    project will occur during a build. Example is a multi-targeted build will have at least
+    //    three evaluations: the outer and both inners
+    // 2. The project start / stop represent the execution of an evaluated project and it is 
+    //    identified with the project context id. The distinction between the two is important
+    //    because other events like task started have context ids but no evaluation ids
+    //
+    //    Note: having a separate context id and evaluation id seems to imply multiple projects
+    //    can run within an evaluation but I haven't actually seen that happen.
+    // 3. Targets / Tasks have context ids but no evaluation ids. 
+    //
+    //    Note: it appears that within a context id these ids are unique but have not rigorously
+    //    validated that.
+    //
+    // Oddities observed
+    //  - There are project start / stop events that have no evaluation id
+
     internal sealed class MSBuildProjectData
     {
         private readonly Dictionary<int, CompilationTaskData> _targetMap = new();
@@ -130,6 +149,7 @@ public static List<CompilerCall> ReadAllCompilerCalls(Stream stream, Func<Compil
         predicate ??= static _ => true;
         var list = new List<CompilerCall>();
         var records = BinaryLog.ReadRecords(stream);
+
         var contextMap = new Dictionary<int, MSBuildProjectData>();
         var evaluationMap = new Dictionary<int, MSBuildEvaluationData>();