Add an optional parameter to the Required annotation

pkg/meta/lib/meta.dart

Index: pkg/meta/lib/meta.dart
diff --git a/pkg/meta/lib/meta.dart b/pkg/meta/lib/meta.dart
index c94fd800f79ac04b5e6e1a5e25770ef924d27183..16411b5def992b9c278a7e8a2e3ed2de5a38ab50 100644
--- a/pkg/meta/lib/meta.dart
+++ b/pkg/meta/lib/meta.dart
@@ -2,7 +2,7 @@
 // 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 such as `@protected`.
+/// Constants for use in metadata annotations.
 ///
 /// See also `@deprecated` and `@override` in the `dart:core` library.
 ///
@@ -84,7 +84,26 @@ const _Protected protected = const _Protected();
 ///   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.
-const _Required required = const _Required();
+const Required required = const Required();
+
+/// Used to annotate a named parameter `p` in a method or function `f`.
+///
+/// See [required] for more details.
+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,
+  ///         ...
+  ///     }) ...
+  final String reason;
+
+  /// Initialize a newly created instance to have the given [reason].
+  const Required([this.reason]);
+}
 
 class _Factory {
   const _Factory();
@@ -101,7 +120,3 @@ class _MustCallSuper {
 class _Protected {
   const _Protected();
 }
-
-class _Required {
-  const _Required();
-}