Add the @immutable annotation

R=pquitslund@google.com

Review URL: https://codereview.chromium.org/2476673004 .

pkg/meta/lib/meta.dart

@@ -18,6 +18,14 @@
 /// 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 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
@@ -30,6 +38,18 @@ library meta;
 ///   can return anything other than a newly allocated object or `null`.
 const _Factory factory = const _Factory();
 
+/// Used to annotate a class `C`. Indicates that `C` and all subtypes of `C`
+/// must be immutable.
+///
+/// A class is immutable if all of the instance fields of the class, whether
+/// defined directly or inherited, are `final`.
+///
+/// Tools, such as the analyzer, can provide feedback if
+/// * the annotation is associated with anything other than a class, or
+/// * a class that has this annotation or extends, implements or mixes in a
+///   class that has this annotation is not immutable.
+const Immutable immutable = const Immutable();
+
 /// Used to annotate a const constructor `c`. Indicates that any invocation of
 /// the constructor must use the keyword `const` unless one or more of the
 /// arguments to the constructor is not a compile-time constant.
@@ -97,6 +117,9 @@ const _Protected protected = const _Protected();
 ///   corresponding to a named parameter that has this annotation.
 const Required required = const Required();
 
+/// Used to annotate a field is allowed to be overridden in Strong Mode.
+const _Virtual virtual = const _Virtual();
+
 /// Used to annotate a declaration was made public, so that it is more visible
 /// than otherwise necessary, to make code testable.
 ///
@@ -109,6 +132,17 @@ const Required required = const Required();
 ///   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;
+
+  /// Initialize a newly created instance to have the given [reason].
+  const Immutable([this.reason]);
+}
+
 /// Used to annotate a named parameter `p` in a method or function `f`.
 ///
 /// See [required] for more details.
@@ -128,17 +162,6 @@ class Required {
   const Required([this.reason]);
 }
 
-/// 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 field is allowed to be overridden in Strong Mode.
-const _Virtual virtual = const _Virtual();
-
 class _Checked {
   const _Checked();
 }