diff --git a/pkg/meta/CHANGELOG.md b/pkg/meta/CHANGELOG.md index abb4cf52ba65..6c396d401e8e 100644 --- a/pkg/meta/CHANGELOG.md +++ b/pkg/meta/CHANGELOG.md @@ -1,7 +1,9 @@ -## 1.12.0 +## 1.12.0-wip -* Introduce the `@ResourceIdentifier` experimental annotation for static methods whose - constant literal arguments should be collected during compilation. +* Introduce the `@ResourceIdentifier` experimental annotation for static methods + whose constant literal arguments should be collected during compilation. +* Indicate that `@required` and `@Required` are set + to be deprecated for later removal. ## 1.11.0 diff --git a/pkg/meta/lib/dart2js.dart b/pkg/meta/lib/dart2js.dart index 29944c86084d..8f4aaf8afd1d 100644 --- a/pkg/meta/lib/dart2js.dart +++ b/pkg/meta/lib/dart2js.dart @@ -2,21 +2,24 @@ // 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 to provide hints to dart2js. +/// Constants for use in metadata annotations to provide hints to dart2js, +/// which is the compiler used by `dart compile js`. /// /// This is an experimental feature and not expected to be useful except for low /// level framework authors. -/// -/// Added at sdk version 2.0.0-dev.6.0 library meta_dart2js; /// An annotation for methods to request that dart2js does not inline the /// method. /// -/// import 'package:meta/dart2js.dart' as dart2js; +/// ```dart +/// import 'package:meta/dart2js.dart' as dart2js; +/// +/// @dart2js.noInline +/// String text() => 'A String of unusual size'; +/// ``` /// -/// @dart2js.noInline -/// String text() => 'A String of unusual size'; +/// It is an error to use both `@noInline` and `@tryInline` on the same method. const noInline = pragma('dart2js:noInline'); /// An annotation for methods to request that dart2js always inline the @@ -26,12 +29,14 @@ const noInline = pragma('dart2js:noInline'); /// this annotation, there are conditions that can prevent dart2js from inlining /// a method, including complex control flow. /// -/// import 'package:meta/dart2js.dart' as dart2js; +/// ```dart +/// import 'package:meta/dart2js.dart' as dart2js; /// -/// @dart2js.tryInline -/// String bigMethod() { -/// for (int i in "Hello".runes) print(i); -/// } +/// @dart2js.tryInline +/// String bigMethod() { +/// for (int i in "Hello".runes) print(i); +/// } +/// ``` /// /// It is an error to use both `@noInline` and `@tryInline` on the same method. const tryInline = pragma('dart2js:tryInline'); diff --git a/pkg/meta/lib/meta.dart b/pkg/meta/lib/meta.dart index 32fed8c0263d..5b3f2cd621d4 100644 --- a/pkg/meta/lib/meta.dart +++ b/pkg/meta/lib/meta.dart @@ -14,11 +14,10 @@ /// 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.dev](https://pub.dev/packages/meta). For examples of using -/// annotations, see -/// [Metadata](https://dart.dev/guides/language/language-tour#metadata) in the -/// language tour. +/// For information on installing and importing this library, +/// see the [meta package on pub.dev](https://pub.dev/packages/meta). +/// To learn more about using annotations, check out the +/// [Metadata](https://dart.dev/language/metadata) documentation. library meta; import 'meta_meta.dart'; @@ -51,6 +50,11 @@ import 'meta_meta.dart'; /// Tools, such as the analyzer, can also expect this contract to be enforced; /// that is, tools may emit warnings if a function with this annotation /// _doesn't_ always throw. +/// +/// **Deprecated:** This annotation is deprecated and will be +/// removed in a future release of `package:meta`. +/// After Dart 2.9, you can instead specify a return type of `Never` +/// to indicate that a function never returns. @Deprecated("Use a return type of 'Never' instead") const _AlwaysThrows alwaysThrows = _AlwaysThrows(); @@ -61,6 +65,9 @@ const _AlwaysThrows alwaysThrows = _AlwaysThrows(); /// its superclass. The actual argument will be checked at runtime to ensure it /// is a subtype of the overridden parameter type. /// +/// **Deprecated:** This annotation is deprecated and will be +/// removed in a future release of `package:meta`. +/// In Dart 2 and later, you can instead use the built-in `covariant` modifier. @Deprecated('Use the `covariant` modifier instead') const _Checked checked = _Checked(); @@ -124,6 +131,7 @@ const _Factory factory = _Factory(); /// 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. @@ -297,8 +305,8 @@ const _Redeclare redeclare = _Redeclare(); /// `final` based on the modifiers of its superinterfaces /// /// A declaration annotated with `@reopen` will suppress warnings from the -/// [`implicit_reopen`](https://dart.dev/tools/linter-rules/implicit_reopen) -/// lint. That lint will otherwise warn when a subtype has restrictions that are +/// [`implicit_reopen`](https://dart.dev/lints/implicit_reopen) lint. +/// That lint will otherwise warn when a subtype has restrictions that are /// not sufficient to enforce the restrictions declared by class modifiers on /// one or more superinterfaces. /// @@ -323,9 +331,17 @@ const _Reopen reopen = _Reopen(); /// 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. +/// +/// **Deprecated:** This annotation is set to be deprecated and later +/// removed in a future release of `package:meta`. +/// In Dart 2.12 and later, use the built-in `required` keyword +/// to mark a named parameter as required. +/// To learn more about `required`, check out the documentation on +/// [named parameters](https://dart.dev/language/functions#named-parameters). const Required required = Required(); -/// Annotation marking a class as not allowed as a super-type. +/// Annotation marking a class as not allowed as a super-type +/// outside of the current package. /// /// Classes in the same package as the marked class may extend, implement or /// mix-in the annotated class. @@ -336,6 +352,11 @@ const Required required = Required(); /// * the annotation is associated with a class `C`, and there is a class or /// mixin `D`, which extends, implements, mixes in, or constrains to `C`, and /// `C` and `D` are declared in different packages. +/// +/// **Note:** In Dart 3 and later, you can use built-in class modifiers to +/// control what forms of subtyping are allowed outside the current library. +/// To learn more about using class modifiers, check out the +/// [Class modifiers](https://dart.dev/language/class-modifiers) documentation. const _Sealed sealed = _Sealed(); /// Used to annotate a method, field, or getter within a class, mixin, or @@ -354,9 +375,11 @@ const UseResult useResult = UseResult(); /// Used to annotate a field that is allowed to be overridden in Strong Mode. /// -/// Deprecated: Most of strong mode is now the default in 2.0, but the notion of -/// virtual fields was dropped, so this annotation no longer has any meaning. -/// Uses of the annotation should be removed. +/// **Deprecated:** This annotation is deprecated and will be +/// removed in a future release of `package:meta`. +/// In Dart 2 and later, overriding fields is allowed by default, +/// so this annotation no longer has any meaning. +/// All uses of the annotation should be removed. @Deprecated('No longer has meaning') const _Virtual virtual = _Virtual(); @@ -408,22 +431,33 @@ class ResourceIdentifier { /// retrieves the annotation. final Object? metadata; + /// Initialize a newly created [ResourceIdentifier] instance + /// to be used as an annotation with the given [metadata] identifier. const ResourceIdentifier([this.metadata]); } /// Used to annotate a named parameter `p` in a method or function `f`. /// /// See [required] for more details. +/// +/// **Deprecated:** This annotation is set to be deprecated and later +/// removed in a future release of `package:meta`. +/// In Dart 2.12 and later, use the built-in `required` keyword +/// to mark a named parameter as required. +/// To learn more about `required`, check out the documentation on +/// [named parameters](https://dart.dev/language/functions#named-parameters). class Required { /// A human-readable explanation of the reason why the annotated parameter is /// required. For example, the annotation might look like: /// - /// ButtonWidget({ - /// Function onHover, - /// @Required('Buttons must do something when pressed') - /// Function onPressed, - /// ... - /// }) ... + /// ```dart + /// ButtonWidget({ + /// Function onHover, + /// @Required('Buttons must do something when pressed') + /// Function onPressed, + /// ... + /// }) ... + /// ``` final String reason; /// Initialize a newly created instance to have the given [reason]. diff --git a/pkg/meta/lib/meta_meta.dart b/pkg/meta/lib/meta_meta.dart index 82ef1fabb3c5..0766c1baabb6 100644 --- a/pkg/meta/lib/meta_meta.dart +++ b/pkg/meta/lib/meta_meta.dart @@ -18,17 +18,26 @@ library meta_meta; /// `const` constructor). /// * the annotated annotation is associated with anything other than the kinds /// of declarations listed as valid targets. +/// +/// This type is not intended to be extended and will be marked as `final` +/// in a future release of `package:meta`. @Target({TargetKind.classType}) class Target { /// The kinds of declarations with which the annotated annotation can be /// associated. final Set kinds; + /// Create a new instance of [Target] to be used as an annotation + /// on a class intended to be used as an annotation, with the + /// specified target [kinds] that it can be applied to. const Target(this.kinds); } /// An enumeration of the kinds of targets to which an annotation can be /// applied. +/// +/// This type is not intended to be extended and will be marked as `final` +/// in a future release of `package:meta`. class TargetKind { /// Indicates that an annotation is valid on any class declaration. static const classType = TargetKind._('classes', 'classType'); @@ -90,6 +99,8 @@ class TargetKind { /// Indicates that an annotation is valid on any typedef declaration.` static const typedefType = TargetKind._('typedefs', 'typedefType'); + /// All current [TargetKind] values of targets to + /// which an annotation can be applied. static const values = [ classType, enumType, @@ -113,8 +124,9 @@ class TargetKind { /// The name of the [TargetKind] value. /// - /// The name is a string containing the source identifier used to declare the [TargetKind] value. - /// For example, the result of `TargetKind.classType.name` is the string "classType". + /// The name is a string containing the source identifier used + /// to declare the [TargetKind] value. For example, + /// the result of `TargetKind.classType.name`is the string "classType". final String name; // This class is not meant to be instantiated or extended; this constructor diff --git a/pkg/meta/pubspec.yaml b/pkg/meta/pubspec.yaml index 4c7ce09a2795..a2bd22494bd4 100644 --- a/pkg/meta/pubspec.yaml +++ b/pkg/meta/pubspec.yaml @@ -1,6 +1,7 @@ name: meta -# Note, because version `2.0.0` was mistakenly released, the next major version must be `3.x.y`. -version: 1.11.0 +# Note, because version `2.0.0` was mistakenly released, +# the next major version must be `3.x.y`. +version: 1.12.0-wip description: >- Annotations used to express developer intentions that can't otherwise be deduced by statically analyzing source code.