OLD | NEW |
| (Empty) |
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | |
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. | |
4 | |
5 part of dart.core; | |
6 | |
7 /** | |
8 * The annotation `@Deprecated('expires when')` marks a feature as deprecated. | |
9 * | |
10 * The annotation `@deprecated` is a shorthand for deprecating until | |
11 * an unspecified "next release". | |
12 * | |
13 * The intent of the `@Deprecated` annotation is to inform users of a feature | |
14 * that they should change their code, even if it is currently still working | |
15 * correctly. | |
16 * | |
17 * A deprecated feature is scheduled to be removed at a later time, possibly | |
18 * specified as the "expires" field of the annotation. | |
19 * This means that a deprecated feature should not be used, or code using it | |
20 * will break at some point in the future. If there is code using the feature, | |
21 * that code should be rewritten to not use the deprecated feature. | |
22 * | |
23 * A deprecated feature should document how the same effect can be achieved, | |
24 * so the programmer knows how to rewrite the code. | |
25 * | |
26 * The `@Deprecated` annotation applies to libraries, top-level declarations | |
27 * (variables, getters, setters, functions, classes and typedefs), | |
28 * class-level declarations (variables, getters, setters, methods, operators or | |
29 * constructors, whether static or not), named optional arguments and | |
30 * trailing optional positional parameters. | |
31 * | |
32 * Deprecation is transitive: | |
33 * | |
34 * - If a library is deprecated, so is every member of it. | |
35 * - If a class is deprecated, so is every member of it. | |
36 * - If a variable is deprecated, so are its implicit getter and setter. | |
37 * | |
38 * | |
39 * A tool that processes Dart source code may report when: | |
40 * | |
41 * - the code imports a deprecated library. | |
42 * - the code exports a deprecated library, or any deprecated member of | |
43 * a non-deprecated library. | |
44 * - the code refers statically to a deprecated declaration. | |
45 * - the code dynamically uses a member of an object with a statically known | |
46 * type, where the member is deprecated on the static type of the object. | |
47 * - the code dynamically calls a method with an argument where the | |
48 * corresponding optional parameter is deprecated on the object's static type. | |
49 * | |
50 * | |
51 * If the deprecated use is inside a library, class or method which is itself | |
52 * deprecated, the tool should not bother the user about it. | |
53 * A deprecated feature is expected to use other deprecated features. | |
54 */ | |
55 class Deprecated { | |
56 /** | |
57 * A description of when the deprecated feature is expected to be retired. | |
58 */ | |
59 final String expires; | |
60 | |
61 /** | |
62 * Create a deprecation annotation which specifies the expiration of the | |
63 * annotated feature. | |
64 * | |
65 * The [expires] argument should be readable by programmers, and should state | |
66 * when an annotated feature is expected to be removed. | |
67 * This can be specified, for example, as a date, as a release number, or | |
68 * as relative to some other change (like "when bug 4418 is fixed"). | |
69 */ | |
70 const Deprecated(String expires) : this.expires = expires; | |
71 | |
72 String toString() => "Deprecated feature. Will be removed $expires"; | |
73 } | |
74 | |
75 class _Override { | |
76 const _Override(); | |
77 } | |
78 | |
79 /** | |
80 * Marks a feature as [Deprecated] until the next release. | |
81 */ | |
82 const Deprecated deprecated = const Deprecated("next release"); | |
83 | |
84 /** | |
85 * The annotation `@override` marks an instance member as overriding a | |
86 * superclass member with the same name. | |
87 * | |
88 * The annotation applies to instance methods, getters and setters, and to | |
89 * instance fields, where it means that the implicit getter and setter of the | |
90 * field is marked as overriding, but the field itself is not. | |
91 * | |
92 * The intent of the `@override` notation is to catch situations where a | |
93 * superclass renames a member, and an independent subclass which used to | |
94 * override the member, could silently continue working using the | |
95 * superclass implementation. | |
96 * | |
97 * The editor, or a similar tool aimed at the programmer, may report if no | |
98 * declaration of an annotated member is inherited by the class from either a | |
99 * superclass or an interface. | |
100 * | |
101 * Use the `@override` annotation judiciously and only for methods where | |
102 * the superclass is not under the programmer's control, the superclass is in a | |
103 * different library or package, and it is not considered stable. | |
104 * In any case, the use of `@override` is optional. | |
105 * | |
106 * For example, the annotation is intentionally not used in the Dart platform | |
107 * libraries, since they only depend on themselves. | |
108 */ | |
109 const Object override = const _Override(); | |
110 | |
111 class _Proxy { | |
112 const _Proxy(); | |
113 } | |
114 | |
115 /** | |
116 * The annotation `@proxy` marks a class as implementing members dynamically | |
117 * through `noSuchMethod`. | |
118 * | |
119 * The annotation applies to any class. It is inherited by subclasses from both | |
120 * superclass and interfaces. | |
121 * | |
122 * If a class is annotated with `@proxy`, or it implements any class that is | |
123 * annotated, then the class is considered to implement any member with regard | |
124 * to static type analysis. | |
125 * As such, it is not a static type warning to access any member of the object | |
126 * which is not implemented by the class, or to call a method with a different | |
127 * number of parameters than it is declared with. | |
128 * | |
129 * The annotation does not change which classes the annotated class implements, | |
130 * and does not prevent static warnings for assigning an object to a variable | |
131 * with a static type not implemented by the object. | |
132 * | |
133 * The suppression of warnings only affect static type warnings about | |
134 * member access. | |
135 * The runtime type of the object is unaffected. | |
136 * It is not considered to implement any special interfaces, | |
137 * so assigning it to a typed variable may fail in checked mode, | |
138 * and testing it with the `is` operator | |
139 * will only return true for types it actually implements or extends. | |
140 * Accessing a member which isn't implemented by the class | |
141 * will cause the `noSuchMethod` method to be called normally, | |
142 * the `@proxy` annotation merely states the intent to handle (some of) those | |
143 * `noSuchMethod` calls gracefully. | |
144 * | |
145 * A class that marked as `@proxy` should override the `noSuchMethod` | |
146 * declared on [Object]. | |
147 * | |
148 * The intent of the `@proxy` notation is to create objects that implement a | |
149 * type (or multiple types) that are not known at compile time. If the types | |
150 * are known at compile time, a class can be written that implements these | |
151 * types. | |
152 */ | |
153 const Object proxy = const _Proxy(); | |
OLD | NEW |