Document throwInternalError

pkg/fletchc/lib/src/diagnostic.dart

Index: pkg/fletchc/lib/src/diagnostic.dart
diff --git a/pkg/fletchc/lib/src/diagnostic.dart b/pkg/fletchc/lib/src/diagnostic.dart
index dab12770ed83171f5b3e960dcd9bb7ceab6808e4..e6d337a673ef42c7799adcd9e0e2e4f126350a53 100644
--- a/pkg/fletchc/lib/src/diagnostic.dart
+++ b/pkg/fletchc/lib/src/diagnostic.dart
@@ -124,6 +124,23 @@ Map<String, String> toDart2jsArguments(
   return result;
 }
 
+/// Throw an internal error that will be recorded as a compiler crash.
+///
+/// In general, assume, no matter how unlikely, that [message] may be read by a
+/// user (that is, a developer using Fletch). For this reason, try to:
+///
+/// * Avoid phrases that can be interpreted as blaming the user (all error
+///   messages should state what is wrong, in a way that doesn't assign blame).
+///
+/// * Avoid being cute or funny (there's nothing more frustrating than being
+///   affected by a bug and see a cute or funny message, especially if it
+///   happens a lot).
+///
+/// * Avoid phrases like "unreachable", "can't happen", "shouldn't happen",
+///   "shouldn't be called", simply because it is wrong: it did happen. In most
+///   cases a factual message would be "unimplemented", "unhandled case",
+///   etc. Remember that the stacktrace will pinpoint the exact location of the
+///   problem, so no need to repeat a method name.
 void throwInternalError(String message) {
   throw new InputError(
       DiagnosticKind.internalError,