Line data Source code
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
3 : // BSD-style license that can be found in the LICENSE file.
4 :
5 : /// Annotations that developers can use to express the intentions that otherwise
6 : /// can't be deduced by statically analyzing the source code.
7 : ///
8 : /// See also `@deprecated` and `@override` in the `dart:core` library.
9 : ///
10 : /// Annotations provide semantic information that tools can use to provide a
11 : /// better user experience. For example, an IDE might not autocomplete the name
12 : /// of a function that's been marked `@deprecated`, or it might display the
13 : /// function's name differently.
14 : ///
15 : /// For information on installing and importing this library, see the [meta
16 : /// package on pub.dev](https://pub.dev/packages/meta). For examples of using
17 : /// annotations, see
18 : /// [Metadata](https://dart.dev/guides/language/language-tour#metadata) in the
19 : /// language tour.
20 : library meta;
21 :
22 : import 'meta_meta.dart';
23 :
24 : /// Used to annotate a function `f`. Indicates that `f` always throws an
25 : /// exception. Any functions that override `f`, in class inheritance, are also
26 : /// expected to conform to this contract.
27 : ///
28 : /// Tools, such as the analyzer, can use this to understand whether a block of
29 : /// code "exits". For example:
30 : ///
31 : /// ```dart
32 : /// @alwaysThrows toss() { throw 'Thrown'; }
33 : ///
34 : /// int fn(bool b) {
35 : /// if (b) {
36 : /// return 0;
37 : /// } else {
38 : /// toss();
39 : /// print("Hello.");
40 : /// }
41 : /// }
42 : /// ```
43 : ///
44 : /// Without the annotation on `toss`, it would look as though `fn` doesn't
45 : /// always return a value. The annotation shows that `fn` does always exit. In
46 : /// addition, the annotation reveals that any statements following a call to
47 : /// `toss` (like the `print` call) are dead code.
48 : ///
49 : /// Tools, such as the analyzer, can also expect this contract to be enforced;
50 : /// that is, tools may emit warnings if a function with this annotation
51 : /// _doesn't_ always throw.
52 : const _AlwaysThrows alwaysThrows = _AlwaysThrows();
53 :
54 : /// Used to annotate a parameter of an instance method that overrides another
55 : /// method.
56 : ///
57 : /// Indicates that this parameter may have a tighter type than the parameter on
58 : /// its superclass. The actual argument will be checked at runtime to ensure it
59 : /// is a subtype of the overridden parameter type.
60 : ///
61 : @Deprecated('Use the `covariant` modifier instead')
62 : const _Checked checked = _Checked();
63 :
64 : /// Used to annotate a method, getter or top-level getter or function to
65 : /// indicate that the value obtained by invoking it should not be stored in a
66 : /// field or top-level variable. The annotation can also be applied to a class
67 : /// to implicitly annotate all of the valid members of the class, or applied to
68 : /// a library to annotate all of the valid members of the library, including
69 : /// classes. If a value returned by an element marked as `doNotStore` is returned
70 : /// from a function or getter, that function or getter should be similarly
71 : /// annotated.
72 : ///
73 : /// Tools, such as the analyzer, can provide feedback if
74 : ///
75 : /// * the annotation is associated with anything other than a library, class,
76 : /// method or getter, top-level getter or function, or
77 : /// * an invocation of a member that has this annotation is returned by a method,
78 : /// getter or function that is not similarly annotated as `doNotStore`, or
79 : /// * an invocation of a member that has this annotation is assigned to a field
80 : /// or top-level variable.
81 : const _DoNotStore doNotStore = _DoNotStore();
82 :
83 : /// Used to annotate a library, or any declaration that is part of the public
84 : /// interface of a library (such as top-level members, class members, and
85 : /// function parameters) to indicate that the annotated API is experimental and
86 : /// may be removed or changed at any-time without updating the version of the
87 : /// containing package, despite the fact that it would otherwise be a breaking
88 : /// change.
89 : ///
90 : /// If the annotation is applied to a library then it is equivalent to applying
91 : /// the annotation to all of the top-level members of the library. Applying the
92 : /// annotation to a class does *not* apply the annotation to subclasses, but
93 : /// does apply the annotation to members of the class.
94 : ///
95 : /// Tools, such as the analyzer, can provide feedback if
96 : ///
97 : /// * the annotation is associated with a declaration that is not part of the
98 : /// public interface of a library (such as a local variable or a declaration
99 : /// that is private) or a directive other than the first directive in the
100 : /// library, or
101 : /// * the declaration is referenced by a package that has not explicitly
102 : /// indicated its intention to use experimental APIs (details TBD).
103 : const _Experimental experimental = _Experimental();
104 :
105 : /// Used to annotate an instance or static method `m`. Indicates that `m` must
106 : /// either be abstract or must return a newly allocated object or `null`. In
107 : /// addition, every method that either implements or overrides `m` is implicitly
108 : /// annotated with this same annotation.
109 : ///
110 : /// Tools, such as the analyzer, can provide feedback if
111 : ///
112 : /// * the annotation is associated with anything other than a method, or
113 : /// * a method that has this annotation can return anything other than a newly
114 : /// allocated object or `null`.
115 : const _Factory factory = _Factory();
116 :
117 : /// Used to annotate a class `C`. Indicates that `C` and all subtypes of `C`
118 : /// must be immutable.
119 : ///
120 : /// A class is immutable if all of the instance fields of the class, whether
121 : /// defined directly or inherited, are `final`.
122 : ///
123 : /// Tools, such as the analyzer, can provide feedback if
124 : /// * the annotation is associated with anything other than a class, or
125 : /// * a class that has this annotation or extends, implements or mixes in a
126 : /// class that has this annotation is not immutable.
127 : const Immutable immutable = Immutable();
128 :
129 : /// Used to annotate a declaration which should only be used from within the
130 : /// package in which it is declared, and which should not be exposed from said
131 : /// package's public API.
132 : ///
133 : /// Tools, such as the analyzer, can provide feedback if
134 : ///
135 : /// * the declaration is declared in a package's public API, or is exposed from
136 : /// a package's public API, or
137 : /// * the declaration is private, an unnamed extension, a static member of a
138 : /// private class, mixin, or extension, a value of a private enum, or a
139 : /// constructor of a private class, or
140 : /// * the declaration is referenced outside the package in which it is declared.
141 : const _Internal internal = _Internal();
142 :
143 : /// Used to annotate a test framework function that runs a single test.
144 : ///
145 : /// Tools, such as IDEs, can show invocations of such function in a file
146 : /// structure view to help the user navigating in large test files.
147 : ///
148 : /// The first parameter of the function must be the description of the test.
149 : const _IsTest isTest = _IsTest();
150 :
151 : /// Used to annotate a test framework function that runs a group of tests.
152 : ///
153 : /// Tools, such as IDEs, can show invocations of such function in a file
154 : /// structure view to help the user navigating in large test files.
155 : ///
156 : /// The first parameter of the function must be the description of the group.
157 : const _IsTestGroup isTestGroup = _IsTestGroup();
158 :
159 : /// Used to annotate a const constructor `c`. Indicates that any invocation of
160 : /// the constructor must use the keyword `const` unless one or more of the
161 : /// arguments to the constructor is not a compile-time constant.
162 : ///
163 : /// Tools, such as the analyzer, can provide feedback if
164 : ///
165 : /// * the annotation is associated with anything other than a const constructor,
166 : /// or
167 : /// * an invocation of a constructor that has this annotation is not invoked
168 : /// using the `const` keyword unless one or more of the arguments to the
169 : /// constructor is not a compile-time constant.
170 : const _Literal literal = _Literal();
171 :
172 : /// Used to annotate an instance method `m`. Indicates that every invocation of
173 : /// a method that overrides `m` must also invoke `m`. In addition, every method
174 : /// that overrides `m` is implicitly annotated with this same annotation.
175 : ///
176 : /// Note that private methods with this annotation cannot be validly overridden
177 : /// outside of the library that defines the annotated method.
178 : ///
179 : /// Tools, such as the analyzer, can provide feedback if
180 : ///
181 : /// * the annotation is associated with anything other than an instance method,
182 : /// or
183 : /// * a method that overrides a method that has this annotation can return
184 : /// without invoking the overridden method.
185 : const _MustCallSuper mustCallSuper = _MustCallSuper();
186 :
187 : /// Used to annotate an instance member (method, getter, setter, operator, or
188 : /// field) `m` in a class `C` or mixin `M`. Indicates that `m` should not be
189 : /// overridden in any classes that extend or mixin `C` or `M`.
190 : ///
191 : /// Tools, such as the analyzer, can provide feedback if
192 : ///
193 : /// * the annotation is associated with anything other than an instance member,
194 : /// * the annotation is associated with an abstract member (because subclasses
195 : /// are required to override the member),
196 : /// * the annotation is associated with an extension method,
197 : /// * the annotation is associated with a member `m` in class `C`, and there is
198 : /// a class `D` or mixin `M`, that extends or mixes in `C`, that declares an
199 : /// overriding member `m`.
200 : const _NonVirtual nonVirtual = _NonVirtual();
201 :
202 : /// Used to annotate a class, mixin, extension, function, method, or typedef
203 : /// declaration `C`. Indicates that any type arguments declared on `C` are to
204 : /// be treated as optional.
205 : ///
206 : /// Tools such as the analyzer and linter can use this information to suppress
207 : /// warnings that would otherwise require type arguments on `C` to be provided.
208 : const _OptionalTypeArgs optionalTypeArgs = _OptionalTypeArgs();
209 :
210 : /// Used to annotate an instance member in a class or mixin which is meant to
211 : /// be visible only within the declaring library, and to other instance members
212 : /// of the class or mixin, and their subtypes.
213 : ///
214 : /// If the annotation is on a field it applies to the getter, and setter if
215 : /// appropriate, that are induced by the field.
216 : ///
217 : /// Indicates that the annotated instance member (method, getter, setter,
218 : /// operator, or field) `m` in a class or mixin `C` should only be referenced
219 : /// in specific locations. A reference from within the library in which `C` is
220 : /// declared is valid. Additionally, a reference from within an instance member
221 : /// in `C`, or a class that extends, implements, or mixes in `C` (either
222 : /// directly or indirectly) or a mixin that uses `C` as a superclass constraint
223 : /// is valid. Additionally a reference from within an instance member in an
224 : /// extension that applies to `C` is valid.
225 : ///
226 : /// Additionally restricts the instance of `C` on which `m` is referenced: a
227 : /// reference to `m` should either be in the same library in which `C` is
228 : /// declared, or should refer to `this.m` (explicitly or implicitly), and not
229 : /// `m` on any other instance of `C`.
230 : ///
231 : /// Tools, such as the analyzer, can provide feedback if
232 : ///
233 : /// * the annotation is associated with anything other than an instance member,
234 : /// or
235 : /// * a reference to a member `m` which has this annotation, declared in a
236 : /// class or mixin `C`, is found outside of the declaring library and outside
237 : /// of an instance member in any class that extends, implements, or mixes in
238 : /// `C` or any mixin that uses `C` as a superclass constraint, or
239 : /// * a reference to a member `m` which has this annotation, declared in a
240 : /// class or mixin `C`, is found outside of the declaring library and the
241 : /// receiver is something other than `this`.
242 : // TODO(srawlins): Add a sentence which defines "referencing" and explicitly
243 : // mentions tearing off, here and on the other annotations which use the word
244 : // "referenced."
245 : const _Protected protected = _Protected();
246 :
247 : /// Used to annotate a named parameter `p` in a method or function `f`.
248 : /// Indicates that every invocation of `f` must include an argument
249 : /// corresponding to `p`, despite the fact that `p` would otherwise be an
250 : /// optional parameter.
251 : ///
252 : /// Tools, such as the analyzer, can provide feedback if
253 : ///
254 : /// * the annotation is associated with anything other than a named parameter,
255 : /// * the annotation is associated with a named parameter in a method `m1` that
256 : /// overrides a method `m0` and `m0` defines a named parameter with the same
257 : /// name that does not have this annotation, or
258 : /// * an invocation of a method or function does not include an argument
259 : /// corresponding to a named parameter that has this annotation.
260 : const Required required = Required();
261 :
262 : /// Annotation marking a class as not allowed as a super-type.
263 : ///
264 : /// Classes in the same package as the marked class may extend, implement or
265 : /// mix-in the annotated class.
266 : ///
267 : /// Tools, such as the analyzer, can provide feedback if
268 : ///
269 : /// * the annotation is associated with anything other than a class,
270 : /// * the annotation is associated with a class `C`, and there is a class or
271 : /// mixin `D`, which extends, implements, mixes in, or constrains to `C`, and
272 : /// `C` and `D` are declared in different packages.
273 : const _Sealed sealed = _Sealed();
274 :
275 : /// Used to annotate a method, field, or getter within a class, mixin, or
276 : /// extension, or a or top-level getter, variable or function to indicate that
277 : /// the value obtained by invoking it should be use. A value is considered used
278 : /// if it is assigned to a variable, passed to a function, or used as the target
279 : /// of an invocation, or invoked (if the result is itself a function).
280 : ///
281 : /// Tools, such as the analyzer, can provide feedback if
282 : ///
283 : /// * the annotation is associated with anything other than a method, field or
284 : /// getter, top-level variable, getter or function or
285 : /// * the value obtained by a method, field, getter or top-level getter,
286 : /// variable or function annotated with `@useResult` is not used.
287 : const UseResult useResult = UseResult();
288 :
289 : /// Used to annotate a field that is allowed to be overridden in Strong Mode.
290 : ///
291 : /// Deprecated: Most of strong mode is now the default in 2.0, but the notion of
292 : /// virtual fields was dropped, so this annotation no longer has any meaning.
293 : /// Uses of the annotation should be removed.
294 : @Deprecated('No longer has meaning')
295 : const _Virtual virtual = _Virtual();
296 :
297 : /// Used to annotate an instance member that was made public so that it could be
298 : /// overridden but that is not intended to be referenced from outside the
299 : /// defining library.
300 : ///
301 : /// Tools, such as the analyzer, can provide feedback if
302 : ///
303 : /// * the annotation is associated with a declaration other than a public
304 : /// instance member in a class or mixin, or
305 : /// * the member is referenced outside of the defining library.
306 : const _VisibleForOverriding visibleForOverriding = _VisibleForOverriding();
307 :
308 : /// Used to annotate a declaration that was made public, so that it is more
309 : /// visible than otherwise necessary, to make code testable.
310 : ///
311 : /// Tools, such as the analyzer, can provide feedback if
312 : ///
313 : /// * the annotation is associated with a declaration not in the `lib` folder
314 : /// of a package, or a private declaration, or a declaration in an unnamed
315 : /// static extension, or
316 : /// * the declaration is referenced outside of its defining library or a
317 : /// library which is in the `test` folder of the defining package.
318 : const _VisibleForTesting visibleForTesting = _VisibleForTesting();
319 :
320 : /// Used to annotate a class.
321 : ///
322 : /// See [immutable] for more details.
323 : class Immutable {
324 : /// A human-readable explanation of the reason why the class is immutable.
325 : final String reason;
326 :
327 : /// Initialize a newly created instance to have the given [reason].
328 11 : const Immutable([this.reason = '']);
329 : }
330 :
331 : /// Used to annotate a named parameter `p` in a method or function `f`.
332 : ///
333 : /// See [required] for more details.
334 : class Required {
335 : /// A human-readable explanation of the reason why the annotated parameter is
336 : /// required. For example, the annotation might look like:
337 : ///
338 : /// ButtonWidget({
339 : /// Function onHover,
340 : /// @Required('Buttons must do something when pressed')
341 : /// Function onPressed,
342 : /// ...
343 : /// }) ...
344 : final String reason;
345 :
346 : /// Initialize a newly created instance to have the given [reason].
347 11 : const Required([this.reason = '']);
348 : }
349 :
350 : /// See [useResult] for more details.
351 : @Target({
352 : TargetKind.field,
353 : TargetKind.function,
354 : TargetKind.getter,
355 : TargetKind.method,
356 : TargetKind.topLevelVariable,
357 : })
358 : class UseResult {
359 : /// A human-readable explanation of the reason why the value returned by
360 : /// accessing this member should be checked.
361 : final String reason;
362 :
363 : /// Initialize a newly created instance to have the given [reason].
364 11 : const UseResult([this.reason = '']);
365 : }
366 :
367 : class _AlwaysThrows {
368 11 : const _AlwaysThrows();
369 : }
370 :
371 : class _Checked {
372 11 : const _Checked();
373 : }
374 :
375 : @Target({
376 : TargetKind.classType,
377 : TargetKind.function,
378 : TargetKind.getter,
379 : TargetKind.library,
380 : TargetKind.method,
381 : })
382 : class _DoNotStore {
383 11 : const _DoNotStore();
384 : }
385 :
386 : class _Experimental {
387 11 : const _Experimental();
388 : }
389 :
390 : class _Factory {
391 11 : const _Factory();
392 : }
393 :
394 : class _Internal {
395 11 : const _Internal();
396 : }
397 :
398 : class _IsTest {
399 11 : const _IsTest();
400 : }
401 :
402 : class _IsTestGroup {
403 11 : const _IsTestGroup();
404 : }
405 :
406 : class _Literal {
407 11 : const _Literal();
408 : }
409 :
410 : class _MustCallSuper {
411 11 : const _MustCallSuper();
412 : }
413 :
414 : class _NonVirtual {
415 11 : const _NonVirtual();
416 : }
417 :
418 : @Target({
419 : TargetKind.classType,
420 : TargetKind.extension,
421 : TargetKind.function,
422 : TargetKind.method,
423 : TargetKind.mixinType,
424 : TargetKind.typedefType,
425 : })
426 : class _OptionalTypeArgs {
427 11 : const _OptionalTypeArgs();
428 : }
429 :
430 : class _Protected {
431 11 : const _Protected();
432 : }
433 :
434 : class _Sealed {
435 11 : const _Sealed();
436 : }
437 :
438 : @Deprecated('No longer has meaning')
439 : class _Virtual {
440 11 : const _Virtual();
441 : }
442 :
443 : class _VisibleForOverriding {
444 11 : const _VisibleForOverriding();
445 : }
446 :
447 : class _VisibleForTesting {
448 11 : const _VisibleForTesting();
449 : }
|