diff --git a/pkg/meta/lib/meta.dart b/pkg/meta/lib/meta.dart index 984287546f65..7fa20e1d177d 100644 --- a/pkg/meta/lib/meta.dart +++ b/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(); }