Add a new 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 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 59 matching lines @@
 /// Tools, such as the analyzer, can provide feedback if
 ///
 /// * the annotation is associated with anything other than a named parameter,
 /// * the annotation is associated with a named parameter in a method `m1` that
 ///   overrides a method `m0` and `m0` defines a named parameter with the same
 ///   name that does not have this annotation, or
 /// * an invocation of a method or function does not include an argument
 ///   corresponding to a named parameter that has this annotation.
 const Required required = const Required();
 
+/// Used to annotate a field that is allowed to be overridden in Strong Mode.
+const _Virtual virtual = const _Virtual();

[Alexei Diaz, 2016/10/13 16:36:58]

Could this somehow be extended to methods? Like the virtual access modifier in
C#.https://msdn.microsoft.com/en-us/library/9fkccyh4.aspx

[Brian Wilkerson, 2016/10/13 18:17:00]

This annotation (which wasn't added by this CL, merely moved when the file was
sorted) is used by DDC to allow more efficient code for fields that are not
annotated. There's currently no other benefit, and DDC currently doesn't provide
any benefit from using it for methods, so I'd hesitate to expand it's use.

+
+/// Used to annotate an instance member that was made public so that it could be
+/// overridden but that is not intended to be referenced from outside the
+/// defining library.
+///
+/// Tools, such as the analyzer, can provide feedback if
+///
+/// * the annotation is associated with a declaration other than a public
+///   instance member in a class, or
+/// * 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
 /// * the declaration is referenced outside of its the defining library or a
 ///   library which is in the `test` folder of the defining package.
@@ skipping 11 matching lines @@
   ///         @Required('Buttons must do something when pressed')
   ///         Function onPressed,
   ///         ...
   ///     }) ...
   final String reason;
 
   /// Initialize a newly created instance to have the given [reason].
   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();
 }
 
 class _Factory {
   const _Factory();
 }
 
 class _Literal {
   const _Literal();
 }
 
 class _MustCallSuper {
   const _MustCallSuper();
 }
 
 class _OptionalTypeArgs {
   const _OptionalTypeArgs();
 }
 
 class _Protected {
   const _Protected();
 }
 
 class _Virtual {
   const _Virtual();
 }
 
+class _VisibleForOverriding {
+  const _VisibleForOverriding();
+}
+
 class _VisibleForTesting {
   const _VisibleForTesting();
 }