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..cf1afffc592ef99f450759aa422fbb584eaf60ce 100644
--- a/pkg/meta/lib/meta.dart
+++ b/pkg/meta/lib/meta.dart
@@ -48,6 +48,36 @@ const _Checked checked = const _Checked();
 ///   indicated its intention to use experimental APIs (details TBD).
 const _Experimental experimental = const _Experimental();
 
+/// 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

[Brian Wilkerson, 2017/06/13 19:35:19]

Please remove the '/'s in the middle of the lines.

[srawlins, 2017/06/13 19:42:04]

Done.

+/// `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 an instance or static method `m`. Indicates that `m` must
 /// either be abstract or must return a newly allocated object or `null`. In
 /// addition, every method that either implements or overrides `m` is implicitly
@@ -195,6 +225,10 @@ class Required {
   const Required([this.reason]);
 }
 
+class _AlwaysThrows {
+  const _AlwaysThrows();
+}
+
 class _Checked {
   const _Checked();
 }