LCOV - code coverage report
Current view: top level - meta-1.7.0/lib - meta.dart (source / functions) Hit Total Coverage
Test: lcov.info Lines: 20 20 100.0 %
Date: 2021-11-28 14:37:50 Functions: 0 0 -

          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             : }

Generated by: LCOV version 1.14