Document concurrent objects in SimplifyTypeNamesDiagnosticAnalyzerBase

src/Features/Core/Portable/SimplifyTypeNames/SimplifyTypeNamesDiagnosticAnalyzerBase.cs

@@ -199,7 +199,31 @@ public DiagnosticAnalyzerCategory GetAnalyzerCategory()
         private class AnalyzerImpl
         {
             private readonly SimplifyTypeNamesDiagnosticAnalyzerBase<TLanguageKindEnum> _analyzer;
-            private readonly ConcurrentDictionary<SyntaxTree, (StrongBox<bool> completed, SimpleIntervalTree<TextSpan, TextSpanIntervalIntrospector>? intervalTree)> _codeBlockIntervals = new ConcurrentDictionary<SyntaxTree, (StrongBox<bool> completed, SimpleIntervalTree<TextSpan, TextSpanIntervalIntrospector>? intervalTree)>();
+
+            /// <summary>
+            /// Tracks the analysis state of syntax trees in a compilation. Each syntax tree has the properties:
+            /// <list type="bullet">
+            /// <item><description>
+            /// <para><c>completed</c>: <see langword="true"/> to indicate that <c>intervalTree</c> has been obtained
+            /// for use in a <see cref="SemanticModelAnalysisContext"/> callback; otherwise, <see langword="false"/> to
+            /// indicate that <c>intervalTree</c> may be updated by adding a new non-overlapping <see cref="TextSpan"/>
+            /// for analysis performed by a <see cref="CodeBlockAnalysisContext"/> callback.</para>
+            ///
+            /// <para>This field also serves as the lock object for updating both <c>completed</c> and
+            /// <c>intervalTree</c>.</para>
+            /// </description></item>
+            /// <item><description>
+            /// <para><c>intervalTree</c>: the set of intervals analyzed by <see cref="CodeBlockAnalysisContext"/>
+            /// callbacks, and therefore do not need to be analyzed again by a
+            /// <see cref="SemanticModelAnalysisContext"/> callback.</para>
+            ///
+            /// <para>This field may only be accessed while <c>completed</c> is locked, and is not valid after
+            /// <c>completed</c> is <see langword="true"/>.</para>
+            /// </description></item>
+            /// </list>
+            /// </summary>
+            private readonly ConcurrentDictionary<SyntaxTree, (StrongBox<bool> completed, SimpleIntervalTree<TextSpan, TextSpanIntervalIntrospector>? intervalTree)> _codeBlockIntervals
+                = new ConcurrentDictionary<SyntaxTree, (StrongBox<bool> completed, SimpleIntervalTree<TextSpan, TextSpanIntervalIntrospector>? intervalTree)>();
 
             public AnalyzerImpl(SimplifyTypeNamesDiagnosticAnalyzerBase<TLanguageKindEnum> analyzer)
             {
@@ -232,9 +256,21 @@ public void AnalyzeCodeBlock(CodeBlockAnalysisContext context)
 
             public void AnalyzeSemanticModel(SemanticModelAnalysisContext context)
             {
+                // Get the state information for the syntax tree. If the state information is not available, it is
+                // initialized directly to a completed state, ensuring that concurrent (or future) calls to
+                // AnalyzeCodeBlock will always read completed==true, and intervalTree does not need to be initialized
+                // to a non-null value.
                 var (completed, intervalTree) = _codeBlockIntervals.GetOrAdd(context.SemanticModel.SyntaxTree, syntaxTree => (new StrongBox<bool>(true), null));
+
+                // Since SemanticModel callbacks only occur once per syntax tree, the completed state can be safely read
+                // here. It will have one of the values:
+                //
+                //   false: the state was initialized in AnalyzeCodeBlock, and intervalTree will be a non-null tree.
+                //   true: the state was initialized on the previous line, and intervalTree will be null.
                 if (!completed.Value)
                 {
+                    // This lock ensures we do not use intervalTree while it is being updated by a concurrent call to
+                    // AnalyzeCodeBlock.
                     lock (completed)
                     {
                         // Prevent future code block callbacks from analyzing more spans within this tree