From 3a26cd21f99771258f257d183bdfc389e780614c Mon Sep 17 00:00:00 2001
From: Cyrus Najmabadi <cyrusn@microsoft.com>
Date: Mon, 6 Jul 2015 15:31:22 -0700
Subject: [PATCH] Adding comments.

---
 src/compiler/checker.ts | 12 +++++++++++-
 src/compiler/program.ts |  7 +++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/compiler/checker.ts b/src/compiler/checker.ts
index 308fe38de71..3ef2c6ada2a 100644
--- a/src/compiler/checker.ts
+++ b/src/compiler/checker.ts
@@ -22,6 +22,17 @@ namespace ts {
     }
 
     export function createTypeChecker(host: TypeCheckerHost, produceDiagnostics: boolean): TypeChecker {
+        // Cancellation that controls whether or not we can cancel in the middle of type checking.
+        // In general cancelling is *not* safe for the type checker.  We might be in the middle of
+        // computing something, and we will leave our internals in an inconsistent state.  Callers
+        // who set the cancellation token should catch if a cancellation exception occurs, and 
+        // should throw away and create a new TypeChecker.
+        //
+        // Currently we only support setting the cancellation token when getting diagnostics.  This
+        // is because diagnostics can be quite expensive, and we want to allow hosts to bail out if
+        // they no longer need the information (for example, if the user started editing again).  
+        let cancellationToken: CancellationToken;
+
         let Symbol = objectAllocator.getSymbolConstructor();
         let Type = objectAllocator.getTypeConstructor();
         let Signature = objectAllocator.getSignatureConstructor();
@@ -13321,7 +13332,6 @@ namespace ts {
             }
         }
 
-        var cancellationToken: CancellationToken;
         function getDiagnostics(sourceFile: SourceFile, ct: CancellationToken): Diagnostic[] {
             try {
                 // Record the cancellation token so it can be checked later on during checkSourceElement.
diff --git a/src/compiler/program.ts b/src/compiler/program.ts
index ae4180cf8be..28efaf24cca 100644
--- a/src/compiler/program.ts
+++ b/src/compiler/program.ts
@@ -313,6 +313,13 @@ namespace ts {
                 if (e instanceof OperationCanceledException) {
                     // We were canceled while performing the operation.  Because our type checker 
                     // might be a bad state, we need to throw it away.
+                    //
+                    // Note: we are overly agressive here.  We do not actually *have* to throw away
+                    // the "noDiagnosticsTypeChecker".  However, for simplicity, i'd like to keep
+                    // the lifetimes of these two TypeCheckers the same.  Also, we generally only
+                    // cancel when the user has made a change anyways.  And, in that case, we (the
+                    // program instance) will get thrown away anyways.  So trying to keep one of 
+                    // these type checkers alive doesn't serve much purpose.
                     noDiagnosticsTypeChecker = undefined;
                     diagnosticsProducingTypeChecker = undefined;
                 }