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

Side by Side Diff: sdk/lib/mirrors/mirrors.dart

Issue 1383403002: Formatting comments for mirrors (MirrorSystem, IsolateMirror, DeclarationMirror, and ObjectMirror) (Closed) Base URL: https://github.com/dart-lang/sdk.git@master
Patch Set: Created 5 years, 2 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 | no next file » | 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) 2013, the Dart project authors. Please see the AUTHORS file 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 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 // For the purposes of the mirrors library, we adopt a naming 5 // For the purposes of the mirrors library, we adopt a naming
6 // convention with respect to getters and setters. Specifically, for 6 // convention with respect to getters and setters. Specifically, for
7 // some variable or field... 7 // some variable or field...
8 // 8 //
9 // var myField; 9 // var myField;
10 // 10 //
(...skipping 52 matching lines...) Expand 10 before | Expand all | Expand 10 after
63 * 63 *
64 * At runtime each running isolate has a distinct [MirrorSystem]. 64 * At runtime each running isolate has a distinct [MirrorSystem].
65 * 65 *
66 * It is also possible to have a [MirrorSystem] which represents a set 66 * It is also possible to have a [MirrorSystem] which represents a set
67 * of libraries which are not running -- perhaps at compile-time. In 67 * of libraries which are not running -- perhaps at compile-time. In
68 * this case, all available reflective functionality would be 68 * this case, all available reflective functionality would be
69 * supported, but runtime functionality (such as invoking a function 69 * supported, but runtime functionality (such as invoking a function
70 * or inspecting the contents of a variable) would fail dynamically. 70 * or inspecting the contents of a variable) would fail dynamically.
71 */ 71 */
72 abstract class MirrorSystem { 72 abstract class MirrorSystem {
73 /** 73 /// Returns an immutable map from URIs to mirrors for all libraries known
Lasse Reichstein Nielsen 2015/10/07 08:32:25 Why change this doc-comment's format, but not the
srawlins 2015/10/07 10:26:29 Sorry, in some other libraries I've been changing
74 * Returns an immutable map from URIs to mirrors for all libraries known 74 /// to this mirror system.
Lasse Reichstein Nielsen 2015/10/07 09:09:03 This is better described as a property: /// All l
srawlins 2015/10/07 10:26:30 Done.
75 * to this mirror system. For a runtime mirror system, only libraries which 75 ///
76 * are currently loaded are included, and repeated calls of this method may 76 /// For a runtime mirror system, only libraries which are currently loaded
77 * return different maps as libraries are loaded. 77 /// are included, and repeated calls of this method may return different maps
78 */ 78 /// as libraries are loaded.
79 Map<Uri, LibraryMirror> get libraries; 79 Map<Uri, LibraryMirror> get libraries;
80 80
81 /** 81 /**
82 * Returns the unique library named [libraryName] if it exists. 82 * Returns the unique library named [libraryName] if it exists.
83 * 83 *
84 * If no unique library exists, an error is thrown. 84 * If no unique library exists, an error is thrown.
85 */ 85 */
86 LibraryMirror findLibrary(Symbol libraryName) { 86 LibraryMirror findLibrary(Symbol libraryName) {
87 return libraries.values.singleWhere( 87 return libraries.values.singleWhere(
88 (library) => library.simpleName == libraryName); 88 (library) => library.simpleName == libraryName);
89 } 89 }
90 90
91 /** 91 /// A mirror on the isolate associated with this [MirrorSystem].
92 * A mirror on the isolate associated with this [MirrorSystem]. 92 ///
93 * This may be null if this mirror system is not running. 93 /// This may be null if this mirror system is not running.
94 */
95 IsolateMirror get isolate; 94 IsolateMirror get isolate;
96 95
97 /** 96 /**
98 * A mirror on the [:dynamic:] type. 97 * A mirror on the [:dynamic:] type.
99 */ 98 */
100 TypeMirror get dynamicType; 99 TypeMirror get dynamicType;
101 100
102 /** 101 /**
103 * A mirror on the [:void:] type. 102 * A mirror on the [:void:] type.
104 */ 103 */
105 TypeMirror get voidType; 104 TypeMirror get voidType;
106 105
107 /** 106 /**
108 * Returns the name of [symbol]. 107 * Returns the name of [symbol].
109 * 108 *
110 * The following text is non-normative: 109 * The following text is non-normative:
111 * 110 *
112 * Using this method may result in larger output. If possible, use 111 * Using this method may result in larger output. If possible, use
113 * [MirrorsUsed] to specify which symbols must be retained in clear text. 112 * [MirrorsUsed] to specify which symbols must be retained in clear text.
114 */ 113 */
115 external static String getName(Symbol symbol); 114 external static String getName(Symbol symbol);
116 115
117 /** 116 /// Returns a symbol for [name].
118 * Returns a symbol for [name]. If [library] is not a [LibraryMirror] or if 117 ///
119 * [name] is a private identifier and [library] is [:null:], throws an 118 /// If [library] is not a [LibraryMirror] or if [name] is a private identifier
120 * [ArgumentError]. If [name] is a private identifier, the symbol returned is 119 /// and [library] is [:null:], throws an [ArgumentError]. If [name] is a
Lasse Reichstein Nielsen 2015/10/07 09:09:02 Cosider changing [:...:] to `...`.
srawlins 2015/10/07 10:26:29 Done.
121 * with respect to [library]. 120 /// private identifier, the symbol returned is with respect to [library].
122 * 121 ///
123 * The following text is non-normative: 122 /// The following text is non-normative:
124 * 123 ///
125 * Using this method may result in larger output. If possible, use 124 /// Using this method may result in larger output. If possible, use
126 * the const constructor of Symbol or symbol literals. 125 /// the const constructor of Symbol or symbol literals.
Lasse Reichstein Nielsen 2015/10/07 09:09:02 maybe: Symbol -> [Symbol]
srawlins 2015/10/07 10:26:30 Done.
127 */
128 external static Symbol getSymbol(String name, [LibraryMirror library]); 126 external static Symbol getSymbol(String name, [LibraryMirror library]);
129 } 127 }
130 128
131 /** 129 /**
132 * Returns a [MirrorSystem] for the current isolate. 130 * Returns a [MirrorSystem] for the current isolate.
133 */ 131 */
134 external MirrorSystem currentMirrorSystem(); 132 external MirrorSystem currentMirrorSystem();
135 133
136 /** 134 /// Reflects an instance.
137 * Reflects an instance. 135 ///
138 * Returns an [InstanceMirror] reflecting [reflectee]. 136 /// Returns an [InstanceMirror] reflecting [reflectee]. If [reflectee] is a
139 * If [reflectee] is a function or an instance of a class 137 /// function or an instance of a class that has a [:call:] method, the returned
140 * that has a [:call:] method, the returned instance mirror 138 /// instance mirror will be a [ClosureMirror].
141 * will be a [ClosureMirror]. 139 ///
142 * 140 /// Note that since one cannot obtain an object from another isolate, this
143 * Note that since one cannot obtain an object from 141 /// function can only be used to obtain mirrors on objects of the current
144 * another isolate, this function can only be used to 142 /// isolate.
145 * obtain mirrors on objects of the current isolate.
146 */
147 external InstanceMirror reflect(Object reflectee); 143 external InstanceMirror reflect(Object reflectee);
148 144
149 /** 145 /// Reflects a class declaration.
150 * Reflects a class declaration. 146 ///
151 * Let *C* be the original class declaration of the class 147 /// Let *C* be the original class declaration of the class represented by [key].
152 * represented by [key]. 148 /// This function returns a [ClassMirror] reflecting *C*.
153 * This function returns a [ClassMirror] reflecting *C*. 149 ///
154 * 150 /// If [key] is not an instance of [Type] then this function throws an
155 * If [key] is not an instance of [Type] then this function 151 /// [ArgumentError]. If [key] is the Type for dynamic or a function typedef,
156 * throws an [ArgumentError]. If [key] is the Type for dynamic 152 /// throws an [ArgumentError].
157 * or a function typedef, throws an [ArgumentError]. 153 ///
158 * 154 /// Note that since one cannot obtain a [Type] object from another isolate, this
159 * Note that since one cannot obtain a [Type] object from 155 /// function can only be used to obtain class mirrors on classes of the current
160 * another isolate, this function can only be used to 156 /// isolate.
161 * obtain class mirrors on classes of the current isolate.
162 */
163 external ClassMirror reflectClass(Type key); 157 external ClassMirror reflectClass(Type key);
164 158
165 /** 159 /// Returns a [TypeMirror] reflecting the type represented by [key].
Lasse Reichstein Nielsen 2015/10/07 09:09:03 Inconsistent wording with the methods above. Maybe
srawlins 2015/10/07 10:26:30 Done.
166 * This function returns a [TypeMirror] reflecting the type 160 ///
167 * represented by [key]. 161 /// If [key] is not an instance of [Type] then this function throws an
168 * 162 /// [ArgumentError].
169 * If [key] is not an instance of [Type] then this function 163 ///
170 * throws an [ArgumentError]. 164 /// Note that since one cannot obtain a [Type] object from another isolate, this
171 * 165 /// function can only be used to obtain type mirrors on types of the current
172 * Note that since one cannot obtain a [Type] object from 166 /// isolate.
173 * another isolate, this function can only be used to
174 * obtain type mirrors on types of the current isolate.
175 */
176 external TypeMirror reflectType(Type key); 167 external TypeMirror reflectType(Type key);
177 168
178 /** 169 /**
179 * A [Mirror] reflects some Dart language entity. 170 * A [Mirror] reflects some Dart language entity.
180 * 171 *
181 * Every [Mirror] originates from some [MirrorSystem]. 172 * Every [Mirror] originates from some [MirrorSystem].
182 */ 173 */
183 abstract class Mirror {} 174 abstract class Mirror {}
184 175
185 /** 176 /**
186 * An [IsolateMirror] reflects an isolate. 177 * An [IsolateMirror] reflects an isolate.
187 */ 178 */
188 abstract class IsolateMirror implements Mirror { 179 abstract class IsolateMirror implements Mirror {
189 /** 180 /// Returns a unique name used to refer to an isolate in debugging messages.
Lasse Reichstein Nielsen 2015/10/07 09:09:02 Describe a getter as a property: /// A unique name
srawlins 2015/10/07 10:26:29 Done.
190 * Returns a unique name used to refer to an isolate
191 * in debugging messages.
192 */
193 String get debugName; 181 String get debugName;
194 182
195 /** 183 /// Returns [:true:] if and only if this mirror reflects the currently running
196 * Returns [:true:] if and only if this mirror reflects 184 /// isolate. Otherwise returns [:false:].
Lasse Reichstein Nielsen 2015/10/07 09:09:02 /// Whether this mirror reflects the currently run
srawlins 2015/10/07 10:26:30 Done.
197 * the currently running isolate. Otherwise returns
198 * [:false:].
199 */
200 bool get isCurrent; 185 bool get isCurrent;
201 186
202 /** 187 /// Returns a [LibraryMirror] on the root library for this isolate.
Lasse Reichstein Nielsen 2015/10/07 09:09:02 /// The root library for the reflected isolate. //
srawlins 2015/10/07 10:26:29 I'm probably not qualified to spell out the defini
203 * Returns a [LibraryMirror] on the root library for this
204 * isolate.
205 */
206 LibraryMirror get rootLibrary; 188 LibraryMirror get rootLibrary;
207 189
208 /** 190 /// Returns [:true:] if this mirror is equal to [other].
209 * Returns [:true:] if this mirror is equal to [other]. 191 ///
210 * Otherwise returns [:false:]. 192 /// Otherwise returns [:false:]. The equality holds if and only if
Lasse Reichstein Nielsen 2015/10/07 09:09:03 /// Whether [other] is an [IsolateMirror] on the s
srawlins 2015/10/07 10:26:29 Done.
211 * The equality holds if and only if 193 ///
212 * (1) [other] is a mirror of the same kind 194 /// 1. [other] is a mirror of the same kind, and
213 * and 195 /// 2. the isolate being reflected by this mirror is the same isolate being
214 * (2) the isolate being reflected by this mirror is the same 196 /// reflected by [other].
215 * isolate being reflected by [other].
216 */
217 bool operator == (other); 197 bool operator == (other);
218 } 198 }
219 199
220 /** 200 /**
221 * A [DeclarationMirror] reflects some entity declared in a Dart program. 201 * A [DeclarationMirror] reflects some entity declared in a Dart program.
222 */ 202 */
223 abstract class DeclarationMirror implements Mirror { 203 abstract class DeclarationMirror implements Mirror {
224 /** 204 /// The simple name for this Dart language entity.
225 * The simple name for this Dart language entity. 205 ///
226 * 206 /// The simple name is in most cases the the identifier name of the entity,
227 * The simple name is in most cases the the identifier name of the 207 /// such as 'method' for a method, [:void method() {...}:] or 'mylibrary' for
Lasse Reichstein Nielsen 2015/10/07 09:09:02 Confusing to use "method". Maybe change to "method
srawlins 2015/10/07 10:26:29 Done.
228 * entity, such as 'method' for a method [:void method() {...}:] or 208 /// a [:library 'mylibrary';:] declaration.
229 * 'mylibrary' for a [:library 'mylibrary';:] declaration.
230 */
231 Symbol get simpleName; 209 Symbol get simpleName;
232 210
233 /** 211 /**
234 * The fully-qualified name for this Dart language entity. 212 * The fully-qualified name for this Dart language entity.
235 * 213 *
236 * This name is qualified by the name of the owner. For instance, 214 * This name is qualified by the name of the owner. For instance,
237 * the qualified name of a method 'method' in class 'Class' in 215 * the qualified name of a method 'method' in class 'Class' in
238 * library 'library' is 'library.Class.method'. 216 * library 'library' is 'library.Class.method'.
239 * 217 *
240 * Returns a [Symbol] constructed from a string representing the 218 * Returns a [Symbol] constructed from a string representing the
241 * fully qualified name of the reflectee. 219 * fully qualified name of the reflectee.
242 * Let *o* be the [owner] of this mirror, let *r* be the reflectee of 220 * Let *o* be the [owner] of this mirror, let *r* be the reflectee of
243 * this mirror, let *p* be the fully qualified 221 * this mirror, let *p* be the fully qualified
244 * name of the reflectee of *o*, and let *s* be the simple name of *r* 222 * name of the reflectee of *o*, and let *s* be the simple name of *r*
245 * computed by [simpleName]. 223 * computed by [simpleName].
246 * The fully qualified name of *r* is the 224 * The fully qualified name of *r* is the
247 * concatenation of *p*, '.', and *s*. 225 * concatenation of *p*, '.', and *s*.
248 * 226 *
249 * Because an isolate can contain more than one library with the same name (at 227 * Because an isolate can contain more than one library with the same name (at
250 * different URIs), a fully-qualified name does not uniquely identify any 228 * different URIs), a fully-qualified name does not uniquely identify any
251 * language entity. 229 * language entity.
252 */ 230 */
253 Symbol get qualifiedName; 231 Symbol get qualifiedName;
254 232
255 /** 233 /// A mirror on the owner of this Dart language entity. This is the
Lasse Reichstein Nielsen 2015/10/07 09:09:02 Newlines before "This". And change "This" to "The
srawlins 2015/10/07 10:26:30 Done.
256 * A mirror on the owner of this Dart language entity. This is the declaration 234 /// declaration immediately surrounding the reflectee.
Lasse Reichstein Nielsen 2015/10/07 09:09:02 Consider changing the final '.' to ':'.
srawlins 2015/10/07 10:26:29 Done.
257 * immediately surrounding the reflectee. 235 ///
258 * 236 /// * For a library, the owner is [:null:].
Lasse Reichstein Nielsen 2015/10/07 09:09:02 These should probably be list items, so add "* " i
srawlins 2015/10/07 10:26:29 Done.
259 * For a library, the owner is [:null:]. 237 /// * For a class declaration, typedef or top level function or variable, the
260 * For a class declaration, typedef or top level function 238 /// owner is the enclosing library.
261 * or variable, the owner is the enclosing library. 239 /// * For a mixin application *S with M*, the owner is the owner of *M*.
Lasse Reichstein Nielsen 2015/10/07 09:09:03 *S with M* -> `S with M` dittos below
srawlins 2015/10/07 10:26:30 Done.
262 * For a mixin application *S with M*, the owner is the owner 240 /// * For a constructor, the owner is the immediately enclosing class.
263 * of *M*. 241 /// * For a method, instance variable or a static variable, the owner is the
264 * For a constructor, the owner is the immediately enclosing class. 242 /// immediately enclosing class, unless the class is a mixin application
265 * For a method, instance variable or 243 /// *S with M*, in which case the owner is *M*. Note that *M* may be an
266 * a static variable, the owner is the immediately enclosing class, 244 /// invocation of a generic.
267 * unless the class is a mixin application *S with M*, in which case 245 /// * For a parameter, local variable or local function the owner is the
268 * the owner is *M*. Note that *M* may be an invocation of a generic. 246 /// immediately enclosing function.
269 * For a parameter, local variable or local function the owner is the
270 * immediately enclosing function.
271 */
272 DeclarationMirror get owner; 247 DeclarationMirror get owner;
273 248
274 /** 249 /// Returns [:true:] if this declaration is considered private according to
Lasse Reichstein Nielsen 2015/10/07 09:09:03 /// Whether this declaration is library private. /
srawlins 2015/10/07 10:26:29 Done.
275 * Returns [:true:] if this declaration is considered private 250 /// the Dart language specification.
276 * according to the Dart language specification. 251 ///
277 * Always returns [: false :] if this declaration 252 /// Always returns [: false :] if this declaration is a library. Otherwise
278 * is a library. 253 /// return [:false:].
279 * Otherwise return [:false:].
280 *
281 */
282 bool get isPrivate; 254 bool get isPrivate;
283 255
284 /** 256 /// Is this declaration top-level?
Lasse Reichstein Nielsen 2015/10/07 09:09:02 /// Whether this declaration is top-level. /// ///
srawlins 2015/10/07 10:26:29 Done.
285 * Is this declaration top-level? 257 ///
286 * 258 /// This is defined to be equivalent to:
287 * This is defined to be equivalent to: 259 /// [:mirror.owner != null && mirror.owner is LibraryMirror:].
288 * [:mirror.owner != null && mirror.owner is LibraryMirror:]
289 */
290 bool get isTopLevel; 260 bool get isTopLevel;
291 261
292 /** 262 /// The source location of this Dart language entity, or [:null:] if the
293 * The source location of this Dart language entity, or [:null:] if the 263 /// entity is synthetic.
294 * entity is synthetic. 264 ///
295 * 265 /// If the reflectee is a variable, the returned location gives the position
296 * If the reflectee is a variable, the returned location gives the position of * the variable name at its point of declaration. 266 /// of the variable name at its point of declaration.
297 * 267 ///
298 * If the reflectee is a library, class, typedef, function or type variable 268 /// If the reflectee is a library, class, typedef, function or type variable
299 * with associated metadata, the returned location gives the position of the 269 /// with associated metadata, the returned location gives the position of the
300 * first metadata declaration associated with the reflectee. 270 /// first metadata declaration associated with the reflectee.
301 * 271 ///
302 * Otherwise: 272 /// Otherwise:
303 * If the reflectee is a library, the returned location gives the position of 273 ///
304 * the keyword 'library' at the reflectee's point of declaration, if the 274 /// If the reflectee is a library, the returned location gives the position of
305 * reflectee is a named library, or the first character of the first line in 275 /// the keyword 'library' at the reflectee's point of declaration, if the
306 * the compilation unit defining the reflectee if the reflectee is anonymous. 276 /// reflectee is a named library, or the first character of the first line in
307 * 277 /// the compilation unit defining the reflectee if the reflectee is anonymous.
308 * If the reflectee is an abstract class, the returned location gives the 278 ///
309 * position of the keyword 'abstract' at the reflectee's point of declaration. * Otherwise, if the reflectee is a class, the returned location gives the 279 /// If the reflectee is an abstract class, the returned location gives the
310 * position of the keyword 'class' at the reflectee's point of declaration. 280 /// position of the keyword 'abstract' at the reflectee's point of declaration .
311 * 281 /// Otherwise, if the reflectee is a class, the returned location gives the
312 * If the reflectee is a typedef the returned location gives the position of 282 /// position of the keyword 'class' at the reflectee's point of declaration.
313 * the of the keyword 'typedef' at the reflectee's point of declaration. 283 ///
314 * 284 /// If the reflectee is a typedef the returned location gives the position of
315 * If the reflectee is a function with a declared return type, the returned 285 /// the of the keyword 'typedef' at the reflectee's point of declaration.
316 * location gives the position of the function's return type at the 286 ///
317 * reflectee's point of declaration. Otherwise. the returned location gives 287 /// If the reflectee is a function with a declared return type, the returned
318 * the position of the function's name at the reflectee's point of 288 /// location gives the position of the function's return type at the
319 * declaration. 289 /// reflectee's point of declaration. Otherwise. the returned location gives
320 * 290 /// the position of the function's name at the reflectee's point of
321 * This operation is optional and may throw an [UnsupportedError]. 291 /// declaration.
Lasse Reichstein Nielsen 2015/10/07 09:09:02 Interesting ... it does not include "static" or "e
srawlins 2015/10/07 10:26:29 Acknowledged.
322 */ 292 ///
293 /// This operation is optional and may throw an [UnsupportedError].
323 SourceLocation get location; 294 SourceLocation get location;
324 295
325 /** 296 /**
326 * A list of the metadata associated with this declaration. 297 * A list of the metadata associated with this declaration.
327 * 298 *
328 * Let *D* be the declaration this mirror reflects. 299 * Let *D* be the declaration this mirror reflects.
329 * If *D* is decorated with annotations *A1, ..., An* 300 * If *D* is decorated with annotations *A1, ..., An*
330 * where *n > 0*, then for each annotation *Ai* associated 301 * where *n > 0*, then for each annotation *Ai* associated
331 * with *D, 1 <= i <= n*, let *ci* be the constant object 302 * with *D, 1 <= i <= n*, let *ci* be the constant object
332 * specified by *Ai*. Then this method returns a list whose 303 * specified by *Ai*. Then this method returns a list whose
(...skipping 16 matching lines...) Expand all
349 * 320 *
350 * For the purposes of the mirrors library, these types are all 321 * For the purposes of the mirrors library, these types are all
351 * object-like, in that they support method invocation and field 322 * object-like, in that they support method invocation and field
352 * access. Real Dart objects are represented by the [InstanceMirror] 323 * access. Real Dart objects are represented by the [InstanceMirror]
353 * type. 324 * type.
354 * 325 *
355 * See [InstanceMirror], [ClassMirror], and [LibraryMirror]. 326 * See [InstanceMirror], [ClassMirror], and [LibraryMirror].
356 */ 327 */
357 abstract class ObjectMirror implements Mirror { 328 abstract class ObjectMirror implements Mirror {
358 329
359 /** 330 /// Invokes the named function and returns a mirror on the result.
360 * Invokes the named function and returns a mirror on the result. 331 ///
361 * 332 /// Let *o* be the object reflected by this mirror, let *f* be the simple name
362 * Let *o* be the object reflected by this mirror, let 333 /// of the member denoted by [memberName], let *a1, ..., an* be the elements
363 * *f* be the simple name of the member denoted by [memberName], 334 /// of [positionalArguments], let *k1, ..., km* be the identifiers denoted by
364 * let *a1, ..., an* be the elements of [positionalArguments] 335 /// the elements of [namedArguments.keys], and let *v1, ..., vm* be the
365 * let *k1, ..., km* be the identifiers denoted by the elements of 336 /// elements of [namedArguments.values]. Then this method will perform the
366 * [namedArguments.keys] 337 /// method invocation *o.f(a1, ..., an, k1: v1, ..., km: vm)* in a scope that
367 * and let *v1, ..., vm* be the elements of [namedArguments.values]. 338 /// has access to the private members of *o* (if *o* is a class or library) or
368 * Then this method will perform the method invocation 339 /// the private members of the class of *o* (otherwise).
Lasse Reichstein Nielsen 2015/10/07 09:09:03 Reflow reduces the readability/editability of the
srawlins 2015/10/07 10:26:29 This means it is equally not readable online: htt
Lasse Reichstein Nielsen 2015/10/07 18:05:56 I think bulleted would be better, maybe reworded a
Lasse Reichstein Nielsen 2015/10/07 18:06:39 I prefer to make it readable in one case rather th
369 * *o.f(a1, ..., an, k1: v1, ..., km: vm)* 340 ///
370 * in a scope that has access to the private members 341 /// If the invocation returns a result *r*, this method returns the result of
371 * of *o* (if *o* is a class or library) or the private members of the 342 /// calling [reflect]\(*r*\).
372 * class of *o* (otherwise). 343 ///
373 * If the invocation returns a result *r*, this method returns 344 /// If the invocation causes a compilation error the effect is the same as if
374 * the result of calling [reflect]\(*r*\). 345 /// a non-reflective compilation error had been encountered.
375 * If the invocation causes a compilation error 346 ///
376 * the effect is the same as if a non-reflective compilation error 347 /// If the invocation throws an exception *e* (that it does not catch), this
377 * had been encountered. 348 /// method throws *e*.
378 * If the invocation throws an exception *e* (that it does not catch)
379 * this method throws *e*.
380 */
381 /* 349 /*
382 * TODO(turnidge): Handle ambiguous names. 350 * TODO(turnidge): Handle ambiguous names.
383 * TODO(turnidge): Handle optional & named arguments. 351 * TODO(turnidge): Handle optional & named arguments.
384 */ 352 */
385 InstanceMirror invoke(Symbol memberName, 353 InstanceMirror invoke(Symbol memberName,
386 List positionalArguments, 354 List positionalArguments,
387 [Map<Symbol,dynamic> namedArguments]); 355 [Map<Symbol,dynamic> namedArguments]);
388 356
389 /** 357 /// Invokes a getter and returns a mirror on the result.
390 * Invokes a getter and returns a mirror on the result. The getter 358 ///
391 * can be the implicit getter for a field or a user-defined getter 359 /// The getter can be the implicit getter for a field or a user-defined getter
392 * method. 360 /// method.
393 * 361 ///
394 * Let *o* be the object reflected by this mirror, let 362 /// Let *o* be the object reflected by this mirror, let *f* be the simple name
Lasse Reichstein Nielsen 2015/10/07 09:09:03 *f* -> `f` More below.
srawlins 2015/10/07 10:26:29 This *f* format is everywhere in this file. Maybe
395 * *f* be the simple name of the getter denoted by [fieldName], 363 /// of the getter denoted by [fieldName]. Then this method will perform the
396 * Then this method will perform the getter invocation 364 /// getter invocation *o.f* in a scope that has access to the private members
397 * *o.f* 365 /// of *o* (if *o* is a class or library) or the private members of the class
398 * in a scope that has access to the private members 366 /// of *o* (otherwise).
399 * of *o* (if *o* is a class or library) or the private members of the 367 ///
400 * class of *o* (otherwise). 368 /// If this mirror is an [InstanceMirror], and [fieldName] denotes an instance
401 * 369 /// method on its reflectee, the result of the invocation is an instance
402 * If this mirror is an [InstanceMirror], and [fieldName] denotes an instance 370 /// mirror on a closure corresponding to that method.
403 * method on its reflectee, the result of the invocation is an instance 371 ///
404 * mirror on a closure corresponding to that method. 372 /// If this mirror is a [LibraryMirror], and [fieldName] denotes a top-level
405 * 373 /// method in the corresponding library, the result of the invocation is an
406 * If this mirror is a [LibraryMirror], and [fieldName] denotes a top-level 374 /// instance mirror on a closure corresponding to that method.
407 * method in the corresponding library, the result of the invocation is an 375 ///
408 * instance mirror on a closure corresponding to that method. 376 /// If this mirror is a [ClassMirror], and [fieldName] denotes a static method
409 * 377 /// in the corresponding class, the result of the invocation is an instance
410 * If this mirror is a [ClassMirror], and [fieldName] denotes a static method 378 /// mirror on a closure corresponding to that method.
411 * in the corresponding class, the result of the invocation is an instance 379 ///
412 * mirror on a closure corresponding to that method. 380 /// If the invocation returns a result *r*, this method returns the result of
413 * 381 /// calling [reflect]\(*r*\).
414 * If the invocation returns a result *r*, this method returns 382 ///
415 * the result of calling [reflect]\(*r*\). 383 /// If the invocation causes a compilation error, the effect is the same as if
416 * If the invocation causes a compilation error 384 /// a non-reflective compilation error had been encountered.
417 * the effect is the same as if a non-reflective compilation error 385 ///
418 * had been encountered. 386 /// If the invocation throws an exception *e* (that it does not catch), this
419 * If the invocation throws an exception *e* (that it does not catch) 387 /// method throws *e*.
420 * this method throws *e*.
421 */
422 // TODO(ahe): Remove stuff about scope and private members. [fieldName] is a 388 // TODO(ahe): Remove stuff about scope and private members. [fieldName] is a
423 // capability giving access to private members. 389 // capability giving access to private members.
424 InstanceMirror getField(Symbol fieldName); 390 InstanceMirror getField(Symbol fieldName);
425 391
426 /** 392 /// Invokes a setter and returns a mirror on the result.
427 * Invokes a setter and returns a mirror on the result. The setter 393 ///
428 * may be either the implicit setter for a non-final field or a 394 /// The setter may be either the implicit setter for a non-final field or a
429 * user-defined setter method. 395 /// user-defined setter method.
430 * 396 ///
431 * Let *o* be the object reflected by this mirror, let 397 /// Let *o* be the object reflected by this mirror, let *f* be the simple name
432 * *f* be the simple name of the getter denoted by [fieldName], 398 /// of the getter denoted by [fieldName], and let *a* be the object bound to
433 * and let *a* be the object bound to [value]. 399 /// [value]. Then this method will perform the setter invocation *o.f = a* in
434 * Then this method will perform the setter invocation 400 /// a scope that has access to the private members of *o* (if *o* is a class
435 * *o.f = a* 401 /// or library) or the private members of the class of *o* (otherwise).
436 * in a scope that has access to the private members 402 ///
437 * of *o* (if *o* is a class or library) or the private members of the 403 /// If the invocation returns a result *r*, this method returns the result of
438 * class of *o* (otherwise). 404 /// calling [reflect]\([value]\).
439 * If the invocation returns a result *r*, this method returns 405 ///
440 * the result of calling [reflect]\([value]\). 406 /// If the invocation causes a compilation error, the effect is the same as if
441 * If the invocation causes a compilation error 407 /// a non-reflective compilation error had been encountered.
442 * the effect is the same as if a non-reflective compilation error 408 ///
443 * had been encountered. 409 /// If the invocation throws an exception *e* (that it does not catch) this
444 * If the invocation throws an exception *e* (that it does not catch) 410 /// method throws *e*.
445 * this method throws *e*.
446 */
447 /* TODO(turnidge): Handle ambiguous names.*/ 411 /* TODO(turnidge): Handle ambiguous names.*/
448 InstanceMirror setField(Symbol fieldName, Object value); 412 InstanceMirror setField(Symbol fieldName, Object value);
449 413
450 /** 414 /// Perform [invocation] on [reflectee].
451 * Perform [invocation] on [reflectee]. 415 ///
452 * Equivalent to 416 /// Equivalent to
453 * 417 ///
454 * if (invocation.isGetter) { 418 /// if (invocation.isGetter) {
455 * return this.getField(invocation.memberName).reflectee; 419 /// return this.getField(invocation.memberName).reflectee;
456 * } else if (invocation.isSetter) { 420 /// } else if (invocation.isSetter) {
457 * return this.setField(invocation.memberName, 421 /// return this.setField(invocation.memberName,
458 * invocation.positionArguments[0]).reflectee; 422 /// invocation.positionArguments[0]).reflectee;
459 * } else { 423 /// } else {
460 * return this.invoke(invocation.memberName, 424 /// return this.invoke(invocation.memberName,
461 * invocation.positionalArguments, 425 /// invocation.positionalArguments,
462 * invocation.namedArguments).reflectee; 426 /// invocation.namedArguments).reflectee;
463 * } 427 /// }
464 */
465 delegate(Invocation invocation); 428 delegate(Invocation invocation);
466 } 429 }
467 430
468 /** 431 /**
469 * An [InstanceMirror] reflects an instance of a Dart language object. 432 * An [InstanceMirror] reflects an instance of a Dart language object.
470 */ 433 */
471 abstract class InstanceMirror implements ObjectMirror { 434 abstract class InstanceMirror implements ObjectMirror {
472 /** 435 /**
473 * A mirror on the type of the reflectee. 436 * A mirror on the type of the reflectee.
474 * 437 *
(...skipping 955 matching lines...) Expand 10 before | Expand all | Expand 10 after
1430 final override; 1393 final override;
1431 1394
1432 /** 1395 /**
1433 * See the documentation for [MirrorsUsed.symbols], [MirrorsUsed.targets], 1396 * See the documentation for [MirrorsUsed.symbols], [MirrorsUsed.targets],
1434 * [MirrorsUsed.metaTargets] and [MirrorsUsed.override] for documentation 1397 * [MirrorsUsed.metaTargets] and [MirrorsUsed.override] for documentation
1435 * of the parameters. 1398 * of the parameters.
1436 */ 1399 */
1437 const MirrorsUsed( 1400 const MirrorsUsed(
1438 {this.symbols, this.targets, this.metaTargets, this.override}); 1401 {this.symbols, this.targets, this.metaTargets, this.override});
1439 } 1402 }
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698