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
@@ skipping 30 matching lines @@
 /// Tools, such as the analyzer, can provide feedback if
 ///
 /// * the annotation is associated with a declaration that is not part of the
 ///   public interface of a library (such as a local variable or a declaration
 ///   that is private) or a directive other than the first directive in the
 ///   library, or
 /// * the declaration is referenced by a package that has not explicitly
 ///   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
 /// 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 127 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 _Checked {
   const _Checked();
 }
 
 class _Experimental {
   const _Experimental();
 }
 
 class _Factory {
   const _Factory();
@@ skipping 19 matching lines @@
   const _Virtual();
 }
 
 class _VisibleForOverriding {
   const _VisibleForOverriding();
 }
 
 class _VisibleForTesting {
   const _VisibleForTesting();
 }