Feedback

src/Build/BackEnd/BuildManager/BuildParameters.cs

@@ -789,7 +789,7 @@ public string OutputResultsCacheFile
         /// Any <see cref="GraphBuildSubmission"/> requests will also use this project cache instead of
         /// the potential project caches described in graph node's evaluations.
         /// </summary>
-        public ProjectCacheDescriptor ProjectCacheDescriptor{ get; set; }
+        public ProjectCacheDescriptor ProjectCacheDescriptor { get; set; }
 
         /// <summary>
         /// Retrieves a toolset.

src/Build/BackEnd/BuildManager/BuildSubmission.cs

@@ -6,9 +6,6 @@
 using Microsoft.Build.BackEnd;
 using Microsoft.Build.Shared;
 using System.Globalization;
-using Microsoft.Build.BackEnd.Logging;
-using Microsoft.Build.BackEnd.SdkResolution;
-using Microsoft.Build.Definition;
 
 namespace Microsoft.Build.Execution
 {

src/Build/BackEnd/Components/ProjectCache/CacheContext.cs

@@ -10,18 +10,28 @@
 namespace Microsoft.Build.Experimental.ProjectCache
 {
     /// <summary>
-    ///     Either Graph is null, or GraphEntryPoints is null. Not Both.
+    ///     Holds various information about the current msbuild execution that the cache might use.
+    ///     The cache may need to know about the top level projects or the entire project graph, so MSBuild
+    ///     provides a graph when one is available. When it isn't available, MSBuild provides the top level projects
+    ///     and the plugin can construct its own graph based on those.
+    ///     So either <see cref="Graph" />is null, or <see cref="GraphEntryPoints" /> is null. But not both.
     /// </summary>
     public class CacheContext
     {
+        public IReadOnlyDictionary<string, string> PluginSettings { get; }
+        public ProjectGraph? Graph { get; }
+        public IReadOnlyCollection<ProjectGraphEntryPoint>? GraphEntryPoints { get; }
+        public string MSBuildExePath { get; }
+        public MSBuildFileSystemBase FileSystem { get; }
+
         public CacheContext(
             IReadOnlyDictionary<string, string> pluginSettings,
             MSBuildFileSystemBase fileSystem,
             ProjectGraph? graph = null,
             IReadOnlyCollection<ProjectGraphEntryPoint>? graphEntryPoints = null)
         {
             ErrorUtilities.VerifyThrow(
-                graph != null ^ graphEntryPoints != null,
+                (graph != null) ^ (graphEntryPoints != null),
                 "Either Graph is specified, or GraphEntryPoints is specified. Not both.");
 
             PluginSettings = pluginSettings;
@@ -30,11 +40,5 @@ public CacheContext(
             MSBuildExePath = BuildEnvironmentHelper.Instance.CurrentMSBuildExePath;
             FileSystem = fileSystem;
         }
-
-        public IReadOnlyDictionary<string, string> PluginSettings { get; }
-        public ProjectGraph? Graph { get; }
-        public IReadOnlyCollection<ProjectGraphEntryPoint>? GraphEntryPoints { get; }
-        public string MSBuildExePath { get; }
-        public MSBuildFileSystemBase FileSystem { get; }
     }
 }

src/Build/BackEnd/Components/ProjectCache/CacheResult.cs

@@ -20,7 +20,10 @@ public enum CacheResultType
     }
 
     /// <summary>
-    ///     Only cache hits have non null build result information.
+    ///     Represents the cache result a plugin returns back to MSBuild when queried about a certain project.
+    ///     Results representing cache hits (with <see cref="ResultType"/> == <see cref="CacheResultType.CacheHit"/>)
+    ///     contain information about what <see cref="Execution.BuildResult"/> MSBuild should use for the queried project.
+    ///     It is assumed that all cache hits result in a successful <see cref="Execution.BuildResult"/>.
     /// </summary>
     public class CacheResult
     {

src/Build/BackEnd/Components/ProjectCache/ProjectCacheDescriptor.cs

@@ -4,7 +4,6 @@
 #nullable enable
 using System.Collections.Generic;
 using System.Linq;
-using Microsoft.Build.Execution;
 using Microsoft.Build.Graph;
 using Microsoft.Build.Shared;