Update comments

src/Workspaces/Core/Portable/Workspace/Solution/ProjectDependencyGraph.cs

@@ -542,13 +542,17 @@ internal ProjectDependencyGraph WithProjectReferenceRemoved(ProjectId projectId,
             Contract.ThrowIfFalse(_projectIds.Contains(projectId));
             Contract.ThrowIfFalse(_referencesMap[projectId].Contains(referencedProjectId));
 
+            // Removing a project reference doesn't change the set of projects
             var projectIds = _projectIds;
+
+            // Incrementally update the graph
             var referencesMap = _referencesMap.SetItem(projectId, _referencesMap[projectId].Remove(referencedProjectId));
             var reverseReferencesMap = _lazyReverseReferencesMap is object
                 ? ComputeNewReverseReferencesMapForRemovedProjectReference(_lazyReverseReferencesMap, projectId, referencedProjectId)
                 : null;
             var transitiveReferencesMap = ComputeNewTransitiveReferencesMapForRemovedProjectReference(_transitiveReferencesMap, projectId, referencedProjectId);
             var reverseTransitiveReferencesMap = ComputeNewReverseTransitiveReferencesMapForRemovedProjectReference(_reverseTransitiveReferencesMap, projectId, referencedProjectId);
+
             return new ProjectDependencyGraph(
                 projectIds,
                 referencesMap,

src/Workspaces/Core/Portable/Workspace/Solution/ProjectState.cs

@@ -617,7 +617,12 @@ public static bool IsSameLanguage(ProjectState project1, ProjectState project2)
             return project1.LanguageServices == project2.LanguageServices;
         }
 
-        public bool ContainsAnyReferenceToProject(ProjectId projectId)
+        /// <summary>
+        /// Determines whether <see cref="ProjectReferences"/> contains a reference to a specified project.
+        /// </summary>
+        /// <param name="projectId">The target project of the reference.</param>
+        /// <returns><see langword="true"/> if this project references <paramref name="projectId"/>; otherwise, <see langword="false"/>.</returns>
+        public bool ContainsReferenceToProject(ProjectId projectId)
         {
             foreach (var projectReference in ProjectReferences)
             {

src/Workspaces/Core/Portable/Workspace/Solution/SolutionState.cs

@@ -956,7 +956,7 @@ public SolutionState RemoveProjectReference(ProjectId projectId, ProjectReferenc
             var newProject = oldProject.RemoveProjectReference(projectReference);
 
             ProjectDependencyGraph newDependencyGraph;
-            if (newProject.ContainsAnyReferenceToProject(projectReference.ProjectId))
+            if (newProject.ContainsReferenceToProject(projectReference.ProjectId))
             {
                 // The project contained multiple references to the project, and not all of them were removed. The
                 // dependency graph doesn't change.
@@ -1829,12 +1829,17 @@ bool CanReuse()
                     if (id == projectId)
                         return true;
 
+                    // Check the dependency graph to see if project 'id' directly or transitively depends on 'projectId'.
+                    // If the information is not available, do not compute it.
                     var forwardDependencies = dependencyGraph.TryGetProjectsThatThisProjectTransitivelyDependsOn(id);
                     if (forwardDependencies is object && !forwardDependencies.Contains(projectId))
                     {
                         return true;
                     }
 
+                    // Compute the set of all projects that depend on 'projectId'. This information answers the same
+                    // question as the previous check, but involves at most one transitive computation within the
+                    // dependency graph.
                     dependencies ??= dependencyGraph.GetProjectsThatTransitivelyDependOnThisProject(projectId);
                     return !dependencies.Contains(id);
                 }