Add an experimental annotation

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
 /// of a function that's been marked `@deprecated`, or it might display the
 /// function's name differently.
 ///
 /// For information on installing and importing this library, see the
 /// [meta package on pub.dartlang.org] (http://pub.dartlang.org/packages/meta).
 /// For examples of using annotations, see
 /// [Metadata](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#metadata)
 /// in the language tour.
 library meta;
 
 /// Used to annotate a parameter of an instance method that overrides another
 /// method.
 ///
 /// Indicates that this parameter may have a tighter type than the parameter on
 /// its superclass. The actual argument will be checked at runtime to ensure it
 /// 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
 /// 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 92 matching lines @@
 /// * the member is referenced outside of the defining library.
 const _VisibleForOverriding visibleForOverriding =
     const _VisibleForOverriding();
 
 /// Used to annotate a declaration was made public, so that it is more visible
 /// than otherwise necessary, to make code testable.
 ///
 /// 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();
 
 /// Used to annotate a class.
 ///
 /// See [immutable] for more details.
 class Immutable {
   /// A human-readable explanation of the reason why the class is immutable.
   final String reason;
@@ skipping 18 matching lines @@
   final String reason;
 
   /// Initialize a newly created instance to have the given [reason].
   const Required([this.reason]);
 }
 
 class _Checked {
   const _Checked();
 }
 
+class _Experimental {
+  const _Experimental();
+}
+
 class _Factory {
   const _Factory();
 }
 
 class _Literal {
   const _Literal();
 }
 
 class _MustCallSuper {
   const _MustCallSuper();
@@ skipping 11 matching lines @@
   const _Virtual();
 }
 
 class _VisibleForOverriding {
   const _VisibleForOverriding();
 }
 
 class _VisibleForTesting {
   const _VisibleForTesting();
 }