[meta] Cleanup API docs and clarify superseded annotation status

This CL standardizes some comment formats, adds a few missing doc comments, and updates a few others.

It also adds text to a few annotations indicating they are likely to be deprecated in a future release and what the migration path is.

Contributes to #54389

Change-Id: I4fc6d9767378b855a1ab2a1978747fbe18850605
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/342281
Reviewed-by: Samuel Rawlins <[email protected]>
Auto-Submit: Parker Lougheed <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>

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
 

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');

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].

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<TargetKind> 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

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.