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

pkg/meta/lib/meta.dart

 // Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /// Constants for use in metadata annotations.
 ///
 /// See also `@deprecated` and `@override` in the `dart:core` library.
 ///
 /// Annotations provide semantic information that tools can use to provide a
 /// better user experience. For example, an IDE might not autocomplete the name
 /// of a function that's been marked `@deprecated`, or it might display the
 /// function's name differently.
 ///
 /// For information on installing and importing this library, see the
 /// [meta package on pub.dartlang.org] (http://pub.dartlang.org/packages/meta).
 /// For examples of using annotations, see
 /// [Metadata](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#metadata)
 /// 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
 /// annotated with this same annotation.
 ///
 /// Tools, such as the analyzer, can provide feedback if
 ///
 /// * the annotation is associated with anything other than a method, or
 /// * the annotation is associated with a method that has this annotation that
 ///   can return anything other than a newly allocated object or `null`.
@@ skipping 78 matching lines @@
   ///         @Required('Buttons must do something when pressed')
   ///         Function onPressed,
   ///         ...
   ///     }) ...
   final String reason;
 
   /// Initialize a newly created instance to have the given [reason].
   const Required([this.reason]);
 }
 
+class _AlwaysThrows {
+  const _AlwaysThrows();
+}
+
 class _Factory {
   const _Factory();
 }
 
 class _Literal {
   const _Literal();
 }
 
 class _MustCallSuper {
   const _MustCallSuper();
 }
 
 class _OptionalTypeArgs {
   const _OptionalTypeArgs();
 }
 
 class _Protected {
   const _Protected();
 }