Add linked file DocumentChanged documentation

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

@@ -162,6 +162,10 @@ public Solution CurrentSolution
         /// <summary>
         /// Sets the <see cref="CurrentSolution"/> of this workspace. This method does not raise a <see cref="WorkspaceChanged"/> event.
         /// </summary>
+        /// <remarks>
+        /// This method does not guarantee that linked files will have the same contents. Callers 
+        /// should enforce that policy before passing in the new solution.
+        /// </remarks>
         protected Solution SetCurrentSolution(Solution solution)
         {
             var currentSolution = Volatile.Read(ref _latestSolution);
@@ -851,7 +855,7 @@ protected internal void OnAdditionalDocumentTextChanged(DocumentId documentId, S
                 newText,
                 mode,
                 CheckAdditionalDocumentIsInCurrentSolution,
-                (solution, docId) => ImmutableArray.Create(docId),
+                (solution, docId) => ImmutableArray.Create(docId), // We do not support the concept of linked additional documents
                 (solution, docId, text, preservationMode) => solution.WithAdditionalDocumentText(docId, text, preservationMode),
                 WorkspaceChangeKind.AdditionalDocumentChanged,
                 isCodeDocument: false);
@@ -894,10 +898,15 @@ private void OnAnyDocumentTextChanged(
                     }
                 }
 
+                // In the case of linked files, we may have already updated all of the linked
+                // documents during an earlier call to this method. We may have no work to do here.
                 if (updatedDocumentIds.Count > 0)
                 {
                     var newSolution = SetCurrentSolution(updatedSolution);
 
+                    // Prior to the unification of the callers of this method, the
+                    // OnAdditionalDocumentTextChanged method did not fire any sort of synchronous
+                    // update notification event, so we preserve that behavior here.
                     if (isCodeDocument)
                     {
                         foreach (var updatedDocumentId in updatedDocumentIds)

src/Workspaces/Core/Portable/Workspace/WorkspaceChangeEventArgs.cs

@@ -4,11 +4,32 @@
 
 namespace Microsoft.CodeAnalysis
 {
+    /// <summary>
+    /// The <see cref="EventArgs"/> describing any kind of workspace change.
+    /// </summary>
+    /// <remarks>
+    /// When linked files are edited, one document change event is fired per linked file. All of
+    /// these events contain the same <see cref="OldSolution"/>, and they all contain the same
+    /// <see cref="NewSolution"/>. This is so that we can trigger document change events on all
+    /// affected documents without reporting intermediate states in which the linked file contents
+    /// do not match.
+    /// </remarks>
     public class WorkspaceChangeEventArgs : EventArgs
     {
         public WorkspaceChangeKind Kind { get; }
+
+        /// <remarks>
+        /// If linked documents are being changed, there may be multiple events with the same
+        /// <see cref="OldSolution"/> and <see cref="NewSolution"/>.
+        /// </remarks>
         public Solution OldSolution { get; }
+
+        /// <remarks>
+        /// If linked documents are being changed, there may be multiple events with the same
+        /// <see cref="OldSolution"/> and <see cref="NewSolution"/>.
+        /// </remarks>
         public Solution NewSolution { get; }
+
         public ProjectId ProjectId { get; }
         public DocumentId DocumentId { get; }
 

src/Workspaces/Core/Portable/Workspace/WorkspaceChangeKind.cs

@@ -68,6 +68,14 @@ public enum WorkspaceChangeKind
         /// <summary>
         /// A document in the current solution was changed.
         /// </summary>
+        /// <remarks>
+        /// When linked files are edited, one <see cref="DocumentChanged"/> event is fired per
+        /// linked file. All of these events contain the same OldSolution, and they all contain
+        /// the same NewSolution. This is so that we can trigger document change events on all
+        /// affected documents without reporting intermediate states in which the linked file
+        /// contents do not match. Each <see cref="DocumentChanged"/> event does not represent
+        /// an incremental update from the previous event in this special case.
+        /// </remarks>
         DocumentChanged = 12,
 
         /// <summary>