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 99a3924683d74e9aa7e2014f28350b92e86d901c..6a53dd86c0c05315b80b460ad6f33aed48999f51 100644
--- a/pkg/meta/lib/meta.dart
+++ b/pkg/meta/lib/meta.dart
@@ -18,6 +18,31 @@
 /// in the language tour.
 library meta;
 
+/// Used to annotate a function `f`. Indicates that `f` always throws an
+/// exception.
+///
+/// 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

[Brian Wilkerson, 2016/07/21 15:39:25]

Not sure why there's a slash on either this line or the next.

+/// addition, the / annotation reveals that any statements following a call to
+/// `toss` (like the `print` call) are dead code.
+const _AlwaysThrows alwaysThrows = const _AlwaysThrows();

[Brian Wilkerson, 2016/07/21 15:39:25]

There are two ways in which this annotation can add value. The first, which you
describe, is to tell us whether a given function always throws an exception.
However, most of the time we could automatically determine that by using static
analysis (there are edge cases where a throw appears inside a try-catch and we
cannot determine the type of the thrown object, but they're probably rare in
practice), which would be more convenient for users.

The second is to declare the developer's intent that the method ought to always
throw an exception and to allow tools to provide a hint when we know that isn't
true (the same edge cases could result in false negatives, but again, they're
probably rare). Intent is something we can't determine from static analysis. :-)
There's nothing in the above description about this second use case. Was that
intentional, or an oversight?

Also, how does this annotation interact with inheritance? For example:

class A {
  @alwaysThrows void fail() { throw 'something'; }
}

class B extends A {
  void fail() { /* do nothing */ } // Should we hint here that the contract is
being violated?
}

int f(B b) {
  b.fail(); // Should we hint here because B.fail isn't guaranteed to throw?
}

I assume we should be able to add this restriction in a subclass, but not remove
it.

+
 /// 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
@@ -116,6 +141,10 @@ class Required {
   const Required([this.reason]);
 }
 
+class _AlwaysThrows {
+  const _AlwaysThrows();
+}
+
 class _Factory {
   const _Factory();
 }