diff --git a/pkg/meta/CHANGELOG.md b/pkg/meta/CHANGELOG.md index 4eed5fe8d437..f8f35a90d60f 100644 --- a/pkg/meta/CHANGELOG.md +++ b/pkg/meta/CHANGELOG.md @@ -1,3 +1,8 @@ +## 1.1.7 + +* Add `unawaited` to mark that a `Future` result is intentionally ignored, + silencing the `unawaited_futures` lint. + ## 1.1.6 * Set max SDK version to <3.0.0. diff --git a/pkg/meta/README.md b/pkg/meta/README.md index c6c710d9d8db..9a926f96a726 100644 --- a/pkg/meta/README.md +++ b/pkg/meta/README.md @@ -1,17 +1,17 @@ # Annotations for Static Analysis -This package defines annotations that can be used by the tools that are shipped -with the Dart SDK. +This package defines annotations, and functions that act like annotations for +expressions, that can be used by the tools that are shipped with the Dart SDK. ## Library Structure The annotations in this package are defined in two libraries. -The library in `meta.dart` defines annotations that can be used by static -analysis tools to provide a more complete analysis of the code that uses them. -Within the SDK, these tools include the command-line analyzer (`dartanalyzer`) -and the analysis server that is used to power many of the Dart-enabled -development tools. +The library in `meta.dart` defines annotations and functions that can be used +by static analysis tools to provide a more complete analysis of the code that +uses them. Within the SDK, these tools include the command-line analyzer +(`dartanalyzer`) and the analysis server that is used to power many of the +Dart-enabled development tools. The library in `dart2js.dart` defines annotations that provide hints to dart2js to improve the quality of the JavaScript code that it produces. These diff --git a/pkg/meta/lib/meta.dart b/pkg/meta/lib/meta.dart index ea23c35ec54c..9cf8c79eb716 100644 --- a/pkg/meta/lib/meta.dart +++ b/pkg/meta/lib/meta.dart @@ -18,6 +18,8 @@ /// in the language tour. library meta; +import 'dart:async' show Future; + /// 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. @@ -244,6 +246,26 @@ class Required { const Required([this.reason]); } +/// Used to indicate to tools that [future] is intentionally not `await`-ed. +/// +/// In an `async` context, it is normally expected than all [Future]s are +/// awaited, and that is the basis of the lint `unawaited_futures`. However, +/// there are times where one or more futures are intentionally not awaited. +/// This function may be used to ignore a particular future. It silences the +/// `unawaited_futures` lint. +/// +/// ``` +/// Future saveUserPreferences() async { +/// await _writePreferences(); +/// +/// // While 'log' returns a Future, the consumer of 'saveUserPreferences' +/// // is unlikely to want to wait for that future to complete; they only +/// // care about the preferences being written). +/// unawaited(log('Preferences saved!')); +/// } +/// ``` +void unawaited(Future future) {} + class _AlwaysThrows { const _AlwaysThrows(); } diff --git a/pkg/meta/pubspec.yaml b/pkg/meta/pubspec.yaml index e908e088dd0a..0d1b4f8abd1b 100644 --- a/pkg/meta/pubspec.yaml +++ b/pkg/meta/pubspec.yaml @@ -1,5 +1,5 @@ name: meta -version: 1.1.6 +version: 1.1.7 author: Dart Team homepage: https://github.com/dart-lang/sdk/tree/master/pkg/meta description: >