Add an alwaysThrows annotation to indicate that a function always throws.

pkg/meta/lib/meta.dart

Index: pkg/meta/lib/meta.dart
diff --git a/pkg/meta/lib/meta.dart b/pkg/meta/lib/meta.dart
index 4b932780df1fac02a4111cab28cb4a37f984c7aa..8dd092768241a75ed8f45876c591efa575b5fd14 100644
--- a/pkg/meta/lib/meta.dart
+++ b/pkg/meta/lib/meta.dart
@@ -18,6 +18,36 @@
 /// in the language tour.
 library meta;
 
+/// Used to annotate a function `f`. Indicates that `f` always throws an
+/// exception. Any functions that override `f`, in class inheritence, are also
+/// expected to conform to this contract.
+///
+/// Tools, such as the analyzer, can use this to understand whether a block of
+/// code "exits". For example:
+///
+/// ```dart
+/// @alwaysThrows toss() { throw 'Thrown'; }
+///
+/// int fn(bool b) {
+///   if (b) {
+///     return 0;
+///   } else {
+///     toss();
+///     print("Hello.");
+///   }
+/// }
+/// ```
+///
+/// Without the annotation on `toss`, it would look as though `fn` doesn't
+/// always return a value. The annotation shows that `fn` does always exit. In
+/// addition, the annotation reveals that any statements following a call to
+/// `toss` (like the `print` call) are dead code.
+///
+/// Tools, such as the analyzer, can also expect this contract to be enforced;
+/// that is, tools may emit warnings if a function with this annotation
+/// _doesn't_ always throw.
+const _AlwaysThrows alwaysThrows = const _AlwaysThrows();
+
 /// Used to annotate a parameter of an instance method that overrides another
 /// method.
 ///
@@ -195,6 +225,10 @@ class Required {
   const Required([this.reason]);
 }
 
+class _AlwaysThrows {
+  const _AlwaysThrows();
+}
+
 class _Checked {
   const _Checked();
 }