Improve compile-time error handling.

pkg/front_end/lib/src/fasta/errors.dart

Index: pkg/front_end/lib/src/fasta/errors.dart
diff --git a/pkg/front_end/lib/src/fasta/errors.dart b/pkg/front_end/lib/src/fasta/errors.dart
index 9e4399dcd84f88a95f5f17dad15a3a416baf5322..077f1609ba19867c24fb8d1581b9735e1b732830 100644
--- a/pkg/front_end/lib/src/fasta/errors.dart
+++ b/pkg/front_end/lib/src/fasta/errors.dart
@@ -34,10 +34,26 @@ bool hasCrashed = false;
 /// [resetCrashReporting].
 Uri firstSourceUri;
 
+/// Used to report an internal error.
+///
+/// Internal errors should be avoided as best as possible, but are preferred
+/// over assertion failures. Favor error messages that starts with "Internal
+/// error: " and a short description that may help a developer debug the issue.
+/// This method should be called instead of using `throw`, as this allows us to
+/// ensure that there are no throws anywhere in the codebase.
 dynamic internalError(Object error) {
   throw error;
 }
 
+/// Used to report an error in input.
+///
+/// Avoid using this for reporting compile-time errors, instead use
+/// `LibraryBuilder.addCompileTimeError` for those.
+///
+/// An input error is any error that isn't an internal error. We use the term
+/// "input error" in favor of "user error". This way, if an input error isn't
+/// handled correctly, the user will never see a stack trace that says "user
+/// error".
 dynamic inputError(Uri uri, int charOffset, Object error) {

[Siggi Cherem (dart-lang), 2017/02/10 23:12:32]

As error-recovery matures is the idea that if we have an input that produces an
input error, we'll work to make it into a recoverable compile-time error and get
rid of the input error?

If so, maybe call this unexpectedInputError to highlight that this should be
used only as a marker that something unexpected happened?

[ahe, 2017/02/13 14:41:02]

There are times when this is the correct method to use, for example, when
reporting an error on a command line option.

I do like the name "unexpectedInput" as this completely removes the word "error"
from the stack trace.

I'll rename this in a future CL.

   throw new InputError(uri, charOffset, error);
 }