OLD | NEW |
1 // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /// Constants for use in metadata annotations. | 5 /// Constants for use in metadata annotations. |
6 /// | 6 /// |
7 /// See also `@deprecated` and `@override` in the `dart:core` library. | 7 /// See also `@deprecated` and `@override` in the `dart:core` library. |
8 /// | 8 /// |
9 /// Annotations provide semantic information that tools can use to provide a | 9 /// Annotations provide semantic information that tools can use to provide a |
10 /// better user experience. For example, an IDE might not autocomplete the name | 10 /// better user experience. For example, an IDE might not autocomplete the name |
11 /// of a function that's been marked `@deprecated`, or it might display the | 11 /// of a function that's been marked `@deprecated`, or it might display the |
12 /// function's name differently. | 12 /// function's name differently. |
13 /// | 13 /// |
14 /// For information on installing and importing this library, see the | 14 /// For information on installing and importing this library, see the |
15 /// [meta package on pub.dartlang.org] (http://pub.dartlang.org/packages/meta). | 15 /// [meta package on pub.dartlang.org] (http://pub.dartlang.org/packages/meta). |
16 /// For examples of using annotations, see | 16 /// For examples of using annotations, see |
17 /// [Metadata](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#metad
ata) | 17 /// [Metadata](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#metad
ata) |
18 /// in the language tour. | 18 /// in the language tour. |
19 library meta; | 19 library meta; |
20 | 20 |
21 /// Used to annotate a parameter of an instance method that overrides another | 21 /// Used to annotate a parameter of an instance method that overrides another |
22 /// method. | 22 /// method. |
23 /// | 23 /// |
24 /// Indicates that this parameter may have a tighter type than the parameter on | 24 /// Indicates that this parameter may have a tighter type than the parameter on |
25 /// its superclass. The actual argument will be checked at runtime to ensure it | 25 /// its superclass. The actual argument will be checked at runtime to ensure it |
26 /// is a subtype of the overridden parameter type. | 26 /// is a subtype of the overridden parameter type. |
27 const _Checked checked = const _Checked(); | 27 const _Checked checked = const _Checked(); |
28 | 28 |
| 29 /// Used to annotate a library, or any declaration that is part of the public |
| 30 /// interface of a library (such as top-level members, class members, and |
| 31 /// function parameters) to indicate that the annotated API is experimental and |
| 32 /// may be removed or changed at any-time without updating the version of the |
| 33 /// containing package, despite the fact that it would otherwise be a breaking |
| 34 /// change. |
| 35 /// |
| 36 /// If the annotation is applied to a library then it is equivalent to applying |
| 37 /// the annotation to all of the top-level members of the library. Applying the |
| 38 /// annotation to a class does *not* apply the annotation to subclasses, but |
| 39 /// does apply the annotation to members of the class. |
| 40 /// |
| 41 /// Tools, such as the analyzer, can provide feedback if |
| 42 /// |
| 43 /// * the annotation is associated with a declaration that is not part of the |
| 44 /// public interface of a library (such as a local variable or a declaration |
| 45 /// that is private) or a directive other than the first directive in the |
| 46 /// library, or |
| 47 /// * the declaration is referenced by a package that has not explicitly |
| 48 /// indicated its intention to use experimental APIs (details TBD). |
| 49 const _Experimental experimental = const _Experimental(); |
| 50 |
29 /// Used to annotate an instance or static method `m`. Indicates that `m` must | 51 /// Used to annotate an instance or static method `m`. Indicates that `m` must |
30 /// either be abstract or must return a newly allocated object or `null`. In | 52 /// either be abstract or must return a newly allocated object or `null`. In |
31 /// addition, every method that either implements or overrides `m` is implicitly | 53 /// addition, every method that either implements or overrides `m` is implicitly |
32 /// annotated with this same annotation. | 54 /// annotated with this same annotation. |
33 /// | 55 /// |
34 /// Tools, such as the analyzer, can provide feedback if | 56 /// Tools, such as the analyzer, can provide feedback if |
35 /// | 57 /// |
36 /// * the annotation is associated with anything other than a method, or | 58 /// * the annotation is associated with anything other than a method, or |
37 /// * the annotation is associated with a method that has this annotation that | 59 /// * the annotation is associated with a method that has this annotation that |
38 /// can return anything other than a newly allocated object or `null`. | 60 /// can return anything other than a newly allocated object or `null`. |
(...skipping 92 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
131 /// * the member is referenced outside of the defining library. | 153 /// * the member is referenced outside of the defining library. |
132 const _VisibleForOverriding visibleForOverriding = | 154 const _VisibleForOverriding visibleForOverriding = |
133 const _VisibleForOverriding(); | 155 const _VisibleForOverriding(); |
134 | 156 |
135 /// Used to annotate a declaration was made public, so that it is more visible | 157 /// Used to annotate a declaration was made public, so that it is more visible |
136 /// than otherwise necessary, to make code testable. | 158 /// than otherwise necessary, to make code testable. |
137 /// | 159 /// |
138 /// Tools, such as the analyzer, can provide feedback if | 160 /// Tools, such as the analyzer, can provide feedback if |
139 /// | 161 /// |
140 /// * the annotation is associated with a declaration not in the `lib` folder | 162 /// * the annotation is associated with a declaration not in the `lib` folder |
141 /// of a package; | 163 /// of a package, or |
142 /// or | |
143 /// * the declaration is referenced outside of its the defining library or a | 164 /// * the declaration is referenced outside of its the defining library or a |
144 /// library which is in the `test` folder of the defining package. | 165 /// library which is in the `test` folder of the defining package. |
145 const _VisibleForTesting visibleForTesting = const _VisibleForTesting(); | 166 const _VisibleForTesting visibleForTesting = const _VisibleForTesting(); |
146 | 167 |
147 /// Used to annotate a class. | 168 /// Used to annotate a class. |
148 /// | 169 /// |
149 /// See [immutable] for more details. | 170 /// See [immutable] for more details. |
150 class Immutable { | 171 class Immutable { |
151 /// A human-readable explanation of the reason why the class is immutable. | 172 /// A human-readable explanation of the reason why the class is immutable. |
152 final String reason; | 173 final String reason; |
(...skipping 18 matching lines...) Expand all Loading... |
171 final String reason; | 192 final String reason; |
172 | 193 |
173 /// Initialize a newly created instance to have the given [reason]. | 194 /// Initialize a newly created instance to have the given [reason]. |
174 const Required([this.reason]); | 195 const Required([this.reason]); |
175 } | 196 } |
176 | 197 |
177 class _Checked { | 198 class _Checked { |
178 const _Checked(); | 199 const _Checked(); |
179 } | 200 } |
180 | 201 |
| 202 class _Experimental { |
| 203 const _Experimental(); |
| 204 } |
| 205 |
181 class _Factory { | 206 class _Factory { |
182 const _Factory(); | 207 const _Factory(); |
183 } | 208 } |
184 | 209 |
185 class _Literal { | 210 class _Literal { |
186 const _Literal(); | 211 const _Literal(); |
187 } | 212 } |
188 | 213 |
189 class _MustCallSuper { | 214 class _MustCallSuper { |
190 const _MustCallSuper(); | 215 const _MustCallSuper(); |
(...skipping 11 matching lines...) Expand all Loading... |
202 const _Virtual(); | 227 const _Virtual(); |
203 } | 228 } |
204 | 229 |
205 class _VisibleForOverriding { | 230 class _VisibleForOverriding { |
206 const _VisibleForOverriding(); | 231 const _VisibleForOverriding(); |
207 } | 232 } |
208 | 233 |
209 class _VisibleForTesting { | 234 class _VisibleForTesting { |
210 const _VisibleForTesting(); | 235 const _VisibleForTesting(); |
211 } | 236 } |
OLD | NEW |