Add an experimental annotation

R=matanl@google.com

Review-Url: https://codereview.chromium.org/2789843003 .

pkg/meta/lib/meta.dart

@@ -26,6 +26,28 @@ library meta;
 /// is a subtype of the overridden parameter type.
 const _Checked checked = const _Checked();
 
+/// Used to annotate a library, or any declaration that is part of the public
+/// interface of a library (such as top-level members, class members, and
+/// function parameters) to indicate that the annotated API is experimental and
+/// may be removed or changed at any-time without updating the version of the
+/// containing package, despite the fact that it would otherwise be a breaking
+/// change.
+///
+/// If the annotation is applied to a library then it is equivalent to applying
+/// the annotation to all of the top-level members of the library. Applying the
+/// annotation to a class does *not* apply the annotation to subclasses, but
+/// does apply the annotation to members of the class.
+///
+/// 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 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
@@ -138,8 +160,7 @@ const _VisibleForOverriding visibleForOverriding =
 /// Tools, such as the analyzer, can provide feedback if
 ///
 /// * the annotation is associated with a declaration not in the `lib` folder
-///   of a package;
-///   or
+///   of a package, or
 /// * the declaration is referenced outside of its the defining library or a
 ///   library which is in the `test` folder of the defining package.
 const _VisibleForTesting visibleForTesting = const _VisibleForTesting();
@@ -178,6 +199,10 @@ class _Checked {
   const _Checked();
 }
 
+class _Experimental {
+  const _Experimental();
+}
+
 class _Factory {
   const _Factory();
 }

pkg/meta/pubspec.yaml

@@ -1,5 +1,5 @@
 name: meta
-version: 1.0.4
+version: 1.0.5
 author: Dart Team <misc@dartlang.org>
 homepage: http://www.dartlang.org
 description: >