Add an optional parameter to the Required annotation

pkg/meta/lib/meta.dart

 // Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
 // 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.
 ///
 /// Annotations provide semantic information that tools can use to provide a
 /// better user experience. For example, an IDE might not autocomplete the name
 /// 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.dartlang.org] (http://pub.dartlang.org/packages/meta).
@@ skipping 61 matching lines @@
 /// corresponding to `p`, despite the fact that `p` would otherwise be an
 /// optional parameter.
 ///
 /// Tools, such as the analyzer, can provide feedback if
 /// * the annotation is associated with anything other than a named parameter,
 /// * the annotation is associated with a named parameter in a method `m1` that
 ///   overrides a method `m0` and `m0` defines a named parameter with the same
 ///   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();
 }
 
 class _Literal {
   const _Literal();
 }
 
 class _MustCallSuper {
   const _MustCallSuper();
 }
 
 class _Protected {
   const _Protected();
 }
-
-class _Required {
-  const _Required();
-}