diff --git a/src/compiler/types.ts b/src/compiler/types.ts
index 07fc909a9aa..3bb937f6e69 100644
--- a/src/compiler/types.ts
+++ b/src/compiler/types.ts
@@ -871,13 +871,15 @@ module ts {
         getPositionFromLineAndCharacter(line: number, character: number): number;
         getLineStarts(): number[];
 
-        // Updates this source file to represent the 'newText' passed in.  The 'textChangeRange' 
-        // parameter indicates what changed between the 'text' that this SourceFile has and the
-        // 'newText'.
+        // Produces a new SourceFile for the 'newText' provided.  The 'textChangeRange' parameter 
+        // indicates what changed between the 'text' that this SourceFile has and the 'newText'.
+        // The SourceFile will be created with the compiler attempting to reuse as many nodes from 
+        // this file as possible.
         //
         // Note: this function mutates nodes from this SourceFile. That means any existing nodes
         // from this SourceFile that are being held onto may change as a result (including 
-        // becoming detached from any SourceFile).
+        // becoming detached from any SourceFile).  It is recommended that this SourceFile not
+        // be used once 'update' is called on it.
         update(newText: string, textChangeRange: TextChangeRange): SourceFile;
 
         amdDependencies: string[];