Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(669)

Side by Side Diff: pkg/meta/lib/meta.dart

Issue 2789843003: Add an experimental annotation (Closed)
Patch Set: Created 3 years, 8 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | pkg/meta/pubspec.yaml » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file 1 // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file
2 // for details. All rights reserved. Use of this source code is governed by a 2 // for details. All rights reserved. Use of this source code is governed by a
3 // BSD-style license that can be found in the LICENSE file. 3 // BSD-style license that can be found in the LICENSE file.
4 4
5 /// Constants for use in metadata annotations. 5 /// Constants for use in metadata annotations.
6 /// 6 ///
7 /// See also `@deprecated` and `@override` in the `dart:core` library. 7 /// See also `@deprecated` and `@override` in the `dart:core` library.
8 /// 8 ///
9 /// Annotations provide semantic information that tools can use to provide a 9 /// Annotations provide semantic information that tools can use to provide a
10 /// better user experience. For example, an IDE might not autocomplete the name 10 /// better user experience. For example, an IDE might not autocomplete the name
11 /// of a function that's been marked `@deprecated`, or it might display the 11 /// of a function that's been marked `@deprecated`, or it might display the
12 /// function's name differently. 12 /// function's name differently.
13 /// 13 ///
14 /// For information on installing and importing this library, see the 14 /// For information on installing and importing this library, see the
15 /// [meta package on pub.dartlang.org] (http://pub.dartlang.org/packages/meta). 15 /// [meta package on pub.dartlang.org] (http://pub.dartlang.org/packages/meta).
16 /// For examples of using annotations, see 16 /// For examples of using annotations, see
17 /// [Metadata](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#metad ata) 17 /// [Metadata](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#metad ata)
18 /// in the language tour. 18 /// in the language tour.
19 library meta; 19 library meta;
20 20
21 /// Used to annotate a parameter of an instance method that overrides another 21 /// Used to annotate a parameter of an instance method that overrides another
22 /// method. 22 /// method.
23 /// 23 ///
24 /// Indicates that this parameter may have a tighter type than the parameter on 24 /// Indicates that this parameter may have a tighter type than the parameter on
25 /// its superclass. The actual argument will be checked at runtime to ensure it 25 /// its superclass. The actual argument will be checked at runtime to ensure it
26 /// is a subtype of the overridden parameter type. 26 /// is a subtype of the overridden parameter type.
27 const _Checked checked = const _Checked(); 27 const _Checked checked = const _Checked();
28 28
29 /// Used to annotate a library, or any declaration that is part of the public
30 /// interface of a library (such as top-level members, class members, and
31 /// function parameters) to indicate that the annotated API is experimental and
32 /// may be removed or changed at any-time without updating the version of the
33 /// containing package, despite the fact that it would otherwise be a breaking
34 /// change.
35 ///
36 /// If the annotation is applied to a library then it is equivalent to applying
37 /// the annotation to all of the top-level members of the library. Applying the
38 /// annotation to a class does *not* apply the annotation to subclasses, but
39 /// does apply the annotation to members of the class.
40 ///
41 /// Tools, such as the analyzer, can provide feedback if
42 ///
43 /// * the annotation is associated with a declaration that is not part of the
44 /// public interface of a library (such as a local variable or a declaration
45 /// that is private) or a directive other than the first directive in the
46 /// library, or
47 /// * the declaration is referenced by a package that has not explicitly
48 /// indicated its intention to use experimental APIs (details TBD).
49 const _Experimental experimental = const _Experimental();
50
29 /// Used to annotate an instance or static method `m`. Indicates that `m` must 51 /// Used to annotate an instance or static method `m`. Indicates that `m` must
30 /// either be abstract or must return a newly allocated object or `null`. In 52 /// either be abstract or must return a newly allocated object or `null`. In
31 /// addition, every method that either implements or overrides `m` is implicitly 53 /// addition, every method that either implements or overrides `m` is implicitly
32 /// annotated with this same annotation. 54 /// annotated with this same annotation.
33 /// 55 ///
34 /// Tools, such as the analyzer, can provide feedback if 56 /// Tools, such as the analyzer, can provide feedback if
35 /// 57 ///
36 /// * the annotation is associated with anything other than a method, or 58 /// * the annotation is associated with anything other than a method, or
37 /// * the annotation is associated with a method that has this annotation that 59 /// * the annotation is associated with a method that has this annotation that
38 /// can return anything other than a newly allocated object or `null`. 60 /// can return anything other than a newly allocated object or `null`.
(...skipping 92 matching lines...) Expand 10 before | Expand all | Expand 10 after
131 /// * the member is referenced outside of the defining library. 153 /// * the member is referenced outside of the defining library.
132 const _VisibleForOverriding visibleForOverriding = 154 const _VisibleForOverriding visibleForOverriding =
133 const _VisibleForOverriding(); 155 const _VisibleForOverriding();
134 156
135 /// Used to annotate a declaration was made public, so that it is more visible 157 /// Used to annotate a declaration was made public, so that it is more visible
136 /// than otherwise necessary, to make code testable. 158 /// than otherwise necessary, to make code testable.
137 /// 159 ///
138 /// Tools, such as the analyzer, can provide feedback if 160 /// Tools, such as the analyzer, can provide feedback if
139 /// 161 ///
140 /// * the annotation is associated with a declaration not in the `lib` folder 162 /// * the annotation is associated with a declaration not in the `lib` folder
141 /// of a package; 163 /// of a package, or
142 /// or
143 /// * the declaration is referenced outside of its the defining library or a 164 /// * the declaration is referenced outside of its the defining library or a
144 /// library which is in the `test` folder of the defining package. 165 /// library which is in the `test` folder of the defining package.
145 const _VisibleForTesting visibleForTesting = const _VisibleForTesting(); 166 const _VisibleForTesting visibleForTesting = const _VisibleForTesting();
146 167
147 /// Used to annotate a class. 168 /// Used to annotate a class.
148 /// 169 ///
149 /// See [immutable] for more details. 170 /// See [immutable] for more details.
150 class Immutable { 171 class Immutable {
151 /// A human-readable explanation of the reason why the class is immutable. 172 /// A human-readable explanation of the reason why the class is immutable.
152 final String reason; 173 final String reason;
(...skipping 18 matching lines...) Expand all
171 final String reason; 192 final String reason;
172 193
173 /// Initialize a newly created instance to have the given [reason]. 194 /// Initialize a newly created instance to have the given [reason].
174 const Required([this.reason]); 195 const Required([this.reason]);
175 } 196 }
176 197
177 class _Checked { 198 class _Checked {
178 const _Checked(); 199 const _Checked();
179 } 200 }
180 201
202 class _Experimental {
203 const _Experimental();
204 }
205
181 class _Factory { 206 class _Factory {
182 const _Factory(); 207 const _Factory();
183 } 208 }
184 209
185 class _Literal { 210 class _Literal {
186 const _Literal(); 211 const _Literal();
187 } 212 }
188 213
189 class _MustCallSuper { 214 class _MustCallSuper {
190 const _MustCallSuper(); 215 const _MustCallSuper();
(...skipping 11 matching lines...) Expand all
202 const _Virtual(); 227 const _Virtual();
203 } 228 }
204 229
205 class _VisibleForOverriding { 230 class _VisibleForOverriding {
206 const _VisibleForOverriding(); 231 const _VisibleForOverriding();
207 } 232 }
208 233
209 class _VisibleForTesting { 234 class _VisibleForTesting {
210 const _VisibleForTesting(); 235 const _VisibleForTesting();
211 } 236 }
OLDNEW
« no previous file with comments | « no previous file | pkg/meta/pubspec.yaml » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698