mirror of
https://github.com/dart-lang/sdk
synced 2024-10-03 01:25:41 +00:00
[dart:core] Adds @Provisional annotation
@Experimental is already defined in dart:html. Adding the same annotation to dart:core breaks the build. Removing the annotation from dart:html and adding it to dart:core is a breaking change, e.g. if someone has said "import 'dart:html' show Experimental". This annotation is for use in the upcoming dart:standalone with the waitFor(Future f) function: https://dart-review.googlesource.com/c/sdk/+/29449 Change-Id: Iea2f537a2ae89a6097c4284084a2a168e833bb04 Reviewed-on: https://dart-review.googlesource.com/30261 Commit-Queue: Zach Anderson <zra@google.com> Reviewed-by: Lasse R.H. Nielsen <lrn@google.com>
This commit is contained in:
parent
4288625d53
commit
3cd62c4b74
|
@ -46,6 +46,7 @@
|
|||
`SECONDS_PER_DAY` to `secondsPerDay`,
|
||||
`MINUTES_PER_DAY` to `minutesPerDay`, and
|
||||
`ZERO` to `zero`.
|
||||
* Added `Provisional` annotation to `dart:core`.
|
||||
|
||||
* `dart:convert`
|
||||
* `Utf8Decoder` when compiled with dart2js uses the browser's `TextDecoder` in
|
||||
|
|
|
@ -72,15 +72,15 @@ class Deprecated {
|
|||
String toString() => "Deprecated feature. Will be removed $expires";
|
||||
}
|
||||
|
||||
class _Override {
|
||||
const _Override();
|
||||
}
|
||||
|
||||
/**
|
||||
* Marks a feature as [Deprecated] until the next release.
|
||||
*/
|
||||
const Deprecated deprecated = const Deprecated("next release");
|
||||
|
||||
class _Override {
|
||||
const _Override();
|
||||
}
|
||||
|
||||
/**
|
||||
* The annotation `@override` marks an instance member as overriding a
|
||||
* superclass member with the same name.
|
||||
|
@ -108,6 +108,59 @@ const Deprecated deprecated = const Deprecated("next release");
|
|||
*/
|
||||
const Object override = const _Override();
|
||||
|
||||
/**
|
||||
* The annotation `@Provisional('message')` marks a feature as provisional.
|
||||
*
|
||||
* An API is considered to be provisional if it is still going through the
|
||||
* process of stabilizing and is subject to change or removal.
|
||||
*
|
||||
* The intent of the `@Provisional` annotation is to mark APIs that are still in
|
||||
* development or that are added only tentatively. Adding the API allows users
|
||||
* to experiment with using the APIs, which can provide valuable feedback. Such
|
||||
* provisional APIs do not promise stability. They can be changed or removed
|
||||
* without warning.
|
||||
*
|
||||
* The `@Provisional` annotation applies to:
|
||||
* - library directives,
|
||||
* - public top-level declarations, and
|
||||
* - public members of public classes.
|
||||
*
|
||||
* Provisionality is transitive:
|
||||
* - If a library is provisional, so is every member of it.
|
||||
* - If a class is provisional, so is every member of it.
|
||||
* - If a variable is provisional, so are its implicit getter and setter.
|
||||
*
|
||||
* Further, if a class is provisional, so are classes that extend, implement,
|
||||
* and mix-in the class.
|
||||
*
|
||||
* A tool that processes Dart source code may report when:
|
||||
* - the code imports a provisional library.
|
||||
* - the code exports a provisional library, or any provisional member of
|
||||
* a non-provisional library.
|
||||
* - the code refers statically to a provisional declaration.
|
||||
* - the code dynamically uses a member of an object with a statically known
|
||||
* type, where the member is provisional on the static type of the object.
|
||||
*
|
||||
* If the provisional use is inside a library, class or method which is itself
|
||||
* provisional, the tool should not bother the user about it.
|
||||
* A provisional feature is expected to use other provisional features.
|
||||
*/
|
||||
class Provisional {
|
||||
/**
|
||||
* A brief message describing how or why the feature is provisional.
|
||||
*/
|
||||
final String message;
|
||||
|
||||
const Provisional({String message})
|
||||
: this.message = message ?? "Subject to change or removal.";
|
||||
}
|
||||
|
||||
/**
|
||||
* Marks a feature as provisional with the message "Subject to change or
|
||||
* removal".
|
||||
*/
|
||||
const Provisional provisional = const Provisional();
|
||||
|
||||
class _Proxy {
|
||||
const _Proxy();
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue