Document when (and when not) to use reportFatalError.

dart/sdk/lib/_internal/compiler/implementation/compiler.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart2js;
 
 /**
  * If true, print a warning for each method that was resolved, but not
  * compiled.
  */
@@ skipping 1604 matching lines @@
                               () => resolver.resolveSignature(element));
   }
 
   void reportError(Spannable node,
                    MessageKind messageKind,
                    [Map arguments = const {}]) {
     reportDiagnosticInternal(
         node, messageKind, arguments, api.Diagnostic.ERROR);
   }
 
+  /**
+   * Reports an error and then aborts the compiler. Avoid using this method.
+   *
+   * In order to support incremental compilation, it is preferable to use
+   * [reportError]. However, care must be taken to leave the compiler in a
+   * consistent state, for example, by creating synthetic erroneous objects.
+   *
+   * If there's absolutely no way to leave the compiler in a consistent state,
+   * calling this method is preferred as it will set [compilerWasCancelled] to
+   * true which alerts the incremental compiler to discard all state and start
+   * a new compiler. Throwing an exception is also better, as this will set
+   * [hasCrashed] which the incremental compiler also listens too (but don't
+   * throw exceptions, it creates a really bad user experience).
+   *
+   * In any case, calling this method is a last resort, as it essentially
+   * breaks the user experience of the incremental compiler. The purpose of the
+   * incremental compiler is to improve developer productivity. Developers
+   * frequently make mistakes, so syntax errors and spelling errors are
+   * considered normal to the incremental compiler.
+   */
   void reportFatalError(Spannable node, MessageKind messageKind,
                         [Map arguments = const {}]) {
     reportError(node, messageKind, arguments);
     // TODO(ahe): Make this only abort the current method.
     throw new CompilerCancelledException(
         'Error: Cannot continue due to previous error.');
   }
 
   void reportWarning(Spannable node, MessageKind messageKind,
                      [Map arguments = const {}]) {
@@ skipping 418 matching lines @@
   static NullSink outputProvider(String name, String extension) {
     return new NullSink('$name.$extension');
   }
 }
 
 /// Information about suppressed warnings and hints for a given library.
 class SuppressionInfo {
   int warnings = 0;
   int hints = 0;
 }