Document when (and when not) to use reportFatalError. (issue 402593002 by ahe@google.com)

[a...@google.com]

Reviewers: Johnni Winther,

Description:
Document when (and when not) to use reportFatalError.

Please review this at https://codereview.chromium.org/402593002/

SVN Base: https://dart.googlecode.com/svn/branches/bleeding_edge

Affected files (+20, -0 lines):
M dart/sdk/lib/_internal/compiler/implementation/compiler.dart


Index: dart/sdk/lib/_internal/compiler/implementation/compiler.dart
diff --git a/dart/sdk/lib/_internal/compiler/implementation/compiler.dart
b/dart/sdk/lib/_internal/compiler/implementation/compiler.dart
index
a08b609bb38773ee24f1b027c123dd8621159ac7..04576357f299fea4b32650de5c9ee61065c6cb5e
100644
--- a/dart/sdk/lib/_internal/compiler/implementation/compiler.dart
+++ b/dart/sdk/lib/_internal/compiler/implementation/compiler.dart
@@ -1622,6 +1622,26 @@ abstract class Compiler implements
DiagnosticListener {
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);

[johnni...@google.com]

lgtm



https://codereview.chromium.org/402593002/