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(); |
} |