@@ -66,22 +66,143 @@ class Deprecated {
6666 /// The message should explain how to migrate away from the feature if an
6767 /// alternative is available, and when the deprecated feature is expected to be
6868 /// removed.
69- final String message;
69+ final String ? message;
7070
71- /// Create a deprecation annotation which specifies the migration path and
71+ final _DeprecationKind _kind;
72+
73+ /// Creates a deprecation annotation which specifies the migration path and
7274 /// expiration of the annotated feature.
7375 ///
74- /// The [message] argument should be readable by programmers, and should state
75- /// an alternative feature (if available) as well as when an annotated feature
76- /// is expected to be removed.
77- const Deprecated (this .message);
76+ /// The [message] is displayed as part of the warning. The message should be
77+ /// aimed at the programmer who owns the extending class, and should
78+ /// recommend an alternative (if available), and say when this functionality
79+ /// is expected to be removed if that is sooner or later than the next major
80+ /// version.
81+ const Deprecated (this .message) : _kind = _DeprecationKind .use;
82+
83+ /// Creates an annotation which deprecates implementing a class or mixin.
84+ ///
85+ /// The annotation can be used on `class` or `mixin` declarations whose
86+ /// interface can currently be implemented, so they are not marked `final` ,
87+ /// `sealed` , or `base` , but where the ability to implement will be removed
88+ /// in a later release.
89+ ///
90+ /// Any existing class, mixin or enum declaration which `implements` the
91+ /// interface will cause a warning that such use is deprecated. Does not
92+ /// affect classes which extend or mix in the annotated class or mixin (see
93+ /// [Deprecated.extend] , [Deprecated.mixin] , and [Deprecated.subclass] ).
94+ ///
95+ /// The annotation is not inherited by subclasses. If a public subclass will
96+ /// also become unimplementable, which it will if the annotated declaration
97+ /// becomes `final` or `base` , but not if it becomes `sealed` , then the
98+ /// subclass should deprecate implementation as well.
99+ ///
100+ /// The [message] , if given, is displayed as part of the warning. The message
101+ /// should be aimed at the programmer who owns the implementing class, and
102+ /// should recommend an alternative (if available), and say when this
103+ /// functionality is expected to be removed if that is sooner or later than
104+ /// the next major version.
105+ const Deprecated .implement ([this .message])
106+ : _kind = _DeprecationKind .implement;
107+
108+ /// Creates an annotation which deprecates extending a class.
109+ ///
110+ /// The annotation can be used on `class` declarations which can currently be
111+ /// extended, so they are not marked `final` , `sealed` , or `interface` , but
112+ /// where the ability to extend will be removed in a later release.
113+ ///
114+ /// Any existing class declaration which `extends` the class will cause a
115+ /// warning that such use is deprecated. Does not affect classes which
116+ /// implement or mix in the annotated class (see [Deprecated.implement] ,
117+ /// [Deprecated.mixin] , and [Deprecated.subclass] ).
118+ ///
119+ /// The annotation is not inherited by subclasses. If a public subclass will
120+ /// also become unextendable, which it will if the annotated declaration
121+ /// becomes `final` or `interface` , but not if it becomes `sealed` , then the
122+ /// subclass should deprecate extendability as well.
123+ ///
124+ /// The [message] , if given, is displayed as part of the warning. The message
125+ /// should be aimed at the programmer who owns the extending class, and
126+ /// should recommend an alternative (if available), and say when this
127+ /// functionality is expected to be removed if that is sooner or later than
128+ /// the next major version.
129+ const Deprecated .extend ([this .message]) : _kind = _DeprecationKind .extend;
130+
131+ /// Creates an annotation which deprecates subclassing (implementing or
132+ /// extending) a class.
133+ ///
134+ /// The annotation can be used on `class` and `mixin` declarations which can
135+ /// currently be subclassed, so they are not marked `final` , or `sealed` , but
136+ /// where the ability to subclass will be removed in a later release.
137+ ///
138+ /// Any existing class declaration which `extends` or `implements` the
139+ /// annotated class or mixin will cause a warning that such use is
140+ /// deprecated. Does not affect classes which mix in the annotated class (see
141+ /// [Deprecated.extend] , [Deprecated.implement] and [Deprecated.mixin] ).
142+ ///
143+ /// The annotation is not inherited by subclasses. If a public subclass will
144+ /// also become unsubclassable, which it will if the annotated declaration
145+ /// becomes `final` , but not if it becomes `sealed` , then the subclass should
146+ /// deprecate subclassability as well.
147+ ///
148+ /// The [message] , if given, is displayed as part of the warning. The message
149+ /// should be aimed at the programmer who owns the subclassing class, and
150+ /// should recommend an alternative (if available), and say when this
151+ /// functionality is expected to be removed if that is sooner or later than
152+ /// the next major version.
153+ const Deprecated .subclass ([this .message]) : _kind = _DeprecationKind .subclass;
154+
155+ /// Creates an annotation which deprecates instantiating a class.
156+ ///
157+ /// The annotation can be used on `class` declarations which can currently be
158+ /// instantiated, so they are not marked `abstract` or `sealed` , but where
159+ /// the ability to instantiate will be removed in a later release.
160+ ///
161+ /// Any existing code which instantiates the annotated class will cause a
162+ /// warning that such use is deprecated.
163+ ///
164+ /// The [message] , if given, is displayed as part of the warning. The message
165+ /// should be aimed at the programmer who owns the instantiating code, and
166+ /// should recommend an alternative (if available), and say when this
167+ /// functionality is expected to be removed if that is sooner or later than
168+ /// the next major version.
169+ const Deprecated .instantiate ([this .message])
170+ : _kind = _DeprecationKind .instantiate;
171+
172+ /// Creates an annotation which deprecates mixing in a class.
173+ ///
174+ /// The annotation can be used on `class` declarations which can currently be
175+ /// mixed in, so they are marked `mixin` , but where the ability to mix in
176+ /// will be removed in a later release.
177+ ///
178+ /// Any existing class declaration which mixes in the annotated class will
179+ /// cause a warning that such use is deprecated. Does not affect classes
180+ /// which extend or implement the annotated class (see [Deprecated.extend] ,
181+ /// [Deprecated.implement] and [Deprecated.subclass] ).
182+ ///
183+ /// The [message] , if given, is displayed as part of the warning. The message
184+ /// should be aimed at the programmer who owns the class which mixes in the
185+ /// annotated class, and should recommend an alternative (if available), and
186+ /// say when this functionality is expected to be removed if that is sooner
187+ /// or later than the next major version.
188+ const Deprecated .mixin ([this .message]) : _kind = _DeprecationKind .mixin ;
78189
79190 String toString () => "Deprecated feature: $message " ;
80191}
81192
82193/// Marks a feature as [Deprecated] until the next release.
83194const Deprecated deprecated = Deprecated ("next release" );
84195
196+ /// The various kinds of deprecations with which a feature can be annotated.
197+ ///
198+ /// Each deprecation kind is paired directly with a [Deprecated] constructor.
199+ /// [_DeprecationKind.use] is used by the unnamed [Deprecated.new] constructor
200+ /// and the [deprecated] constant.
201+ ///
202+ /// This enum can be private because the information is only intended for
203+ /// static tooling, such as the analyzer. Values may be added.
204+ enum _DeprecationKind { use, implement, extend, subclass, instantiate, mixin }
205+
85206class _Override {
86207 const _Override ();
87208}
0 commit comments