@@ -82,11 +82,11 @@ class Method extends Node {
82
82
83
83
/// Whether this method is required to be implemented.
84
84
///
85
- /// This flag is typically used to determine whether a callback method for
86
- /// a `ProxyApi` is nullable or not .
85
+ /// This flag is typically only used to determine whether a callback method
86
+ /// for an instance of a Dart proxy class of a ProxyAPI is nonnull .
87
87
bool isRequired;
88
88
89
- /// Whether this is a static method of a ProxyApi .
89
+ /// Whether the method of an [AstProxyApi] is denoted with [static] .
90
90
bool isStatic;
91
91
92
92
@override
@@ -134,7 +134,7 @@ class AstFlutterApi extends Api {
134
134
}
135
135
}
136
136
137
- /// Represents an API that wraps a native class .
137
+ /// Represents the AST for the class denoted with the ProxyAPI annotation .
138
138
class AstProxyApi extends Api {
139
139
/// Parametric constructor for [AstProxyApi] .
140
140
AstProxyApi ({
@@ -149,16 +149,16 @@ class AstProxyApi extends Api {
149
149
this .kotlinOptions,
150
150
});
151
151
152
- /// List of constructors inside the API .
152
+ /// List of constructors declared in the class .
153
153
final List <Constructor > constructors;
154
154
155
- /// List of fields inside the API .
155
+ /// List of fields declared in the class .
156
156
List <ApiField > fields;
157
157
158
- /// Name of the class this class considers the super class.
158
+ /// A [TypeDeclaration] of the parent class if the class had one .
159
159
TypeDeclaration ? superClass;
160
160
161
- /// Name of the classes this class considers to be implemented .
161
+ /// A set of [TypeDeclaration] s that this class implements .
162
162
Set <TypeDeclaration > interfaces;
163
163
164
164
/// Options that control how Swift code will be generated for a specific
@@ -169,12 +169,12 @@ class AstProxyApi extends Api {
169
169
/// ProxyApi.
170
170
final KotlinProxyApiOptions ? kotlinOptions;
171
171
172
- /// Methods implemented in the host platform language .
172
+ /// Methods that handled by an implementation of the native type api .
173
173
Iterable <Method > get hostMethods => methods.where (
174
174
(Method method) => method.location == ApiLocation .host,
175
175
);
176
176
177
- /// Methods implemented in Flutter .
177
+ /// Methods that are handled by an instance of the Dart proxy class .
178
178
Iterable <Method > get flutterMethods => methods.where (
179
179
(Method method) => method.location == ApiLocation .flutter,
180
180
);
@@ -193,15 +193,16 @@ class AstProxyApi extends Api {
193
193
(ApiField field) => ! field.isAttached,
194
194
);
195
195
196
- /// A list of AstProxyApis where each `extends` the API that follows it.
196
+ /// A list of [AstProxyApi] s where each is the [superClass] of the one
197
+ /// proceeding it.
197
198
///
198
- /// Returns an empty list if this api does not extend a ProxyApi .
199
+ /// Returns an empty list if this class did not provide a [superClass] .
199
200
///
200
- /// This method assumes the super classes of each ProxyApi doesn't create a
201
- /// loop. Throws a [ArgumentError] if a loop is found.
201
+ /// This method assumes the [superClass] of each class doesn't lead to a loop
202
+ /// Throws a [ArgumentError] if a loop is found.
202
203
///
203
- /// This method also assumes that all super classes are ProxyApis. Otherwise,
204
- /// throws an [ArgumentError] .
204
+ /// This method also assumes that the type of [superClass] is annotated with
205
+ /// `@ProxyApi` . Otherwise, throws an [ArgumentError] .
205
206
Iterable <AstProxyApi > allSuperClasses () {
206
207
final List <AstProxyApi > superClassChain = < AstProxyApi > [];
207
208
@@ -236,12 +237,12 @@ class AstProxyApi extends Api {
236
237
return superClassChain;
237
238
}
238
239
239
- /// All ProxyApis this API `implements` and all the interfaces those APIs
240
+ /// All classes this class `implements` and all the interfaces those classes
240
241
/// `implements` .
241
242
Iterable <AstProxyApi > apisOfInterfaces () => _recursiveFindAllInterfaceApis ();
242
243
243
- /// Returns a record for each method inherited from an interface and its
244
- /// corresponding ProxyApi .
244
+ /// Returns a record for each Flutter method inherited from an interface and
245
+ /// the AST of its corresponding class .
245
246
Iterable <(Method , AstProxyApi )> flutterMethodsFromInterfacesWithApis () sync * {
246
247
for (final AstProxyApi proxyApi in apisOfInterfaces ()) {
247
248
yield * proxyApi.methods.map ((Method method) => (method, proxyApi));
@@ -250,8 +251,7 @@ class AstProxyApi extends Api {
250
251
251
252
/// Returns a record for each Flutter method inherited from [superClass] .
252
253
///
253
- /// This also includes methods that super classes inherited from interfaces
254
- /// with `implements` .
254
+ /// This also includes methods that the [superClass] inherits from interfaces.
255
255
Iterable <(Method , AstProxyApi )>
256
256
flutterMethodsFromSuperClassesWithApis () sync * {
257
257
for (final AstProxyApi proxyApi in allSuperClasses ().toList ().reversed) {
@@ -266,51 +266,50 @@ class AstProxyApi extends Api {
266
266
}
267
267
}
268
268
269
- /// All methods inherited from interfaces and the interfaces of interfaces .
269
+ /// All methods inherited from interfaces.
270
270
Iterable <Method > flutterMethodsFromInterfaces () sync * {
271
271
yield * flutterMethodsFromInterfacesWithApis ().map (
272
272
((Method , AstProxyApi ) method) => method.$1,
273
273
);
274
274
}
275
275
276
- /// A list of Flutter methods inherited from the ProxyApi that this ProxyApi
277
- /// `extends` .
276
+ /// A list of Flutter methods inherited from [superClass] .
278
277
///
279
- /// This also recursively checks the ProxyApi that the super class `extends`
280
- /// and so on.
278
+ /// This also recursively checks the [superClass] of [superClass] .
281
279
///
282
- /// This also includes methods that super classes inherited from interfaces
283
- /// with `implements` .
280
+ /// This also includes methods that [superClass] inherits from interfaces with
281
+ /// `implements` .
284
282
Iterable <Method > flutterMethodsFromSuperClasses () sync * {
285
283
yield * flutterMethodsFromSuperClassesWithApis ().map (
286
284
((Method , AstProxyApi ) method) => method.$1,
287
285
);
288
286
}
289
287
290
- /// Whether the API has a method that callbacks to Dart to add a new instance
291
- /// to the InstanceManager .
288
+ /// Whether the generated ProxyAPI should generate a method in the native type
289
+ /// API that calls to Dart to instantiate a Dart proxy class instance .
292
290
///
293
- /// This is possible as long as no callback methods are required to
294
- /// instantiate the class.
291
+ /// This is possible as the class does not contain a method that is required
292
+ /// to be handled by an instance of the Dart proxy class.
295
293
bool hasCallbackConstructor () {
296
294
return flutterMethods
297
295
.followedBy (flutterMethodsFromSuperClasses ())
298
296
.followedBy (flutterMethodsFromInterfaces ())
299
297
.every ((Method method) => ! method.isRequired);
300
298
}
301
299
302
- /// Whether the API has any message calls from Dart to host.
300
+ /// Whether the Dart proxy class makes any message calls to the native type
301
+ /// API.
303
302
bool hasAnyHostMessageCalls () =>
304
303
constructors.isNotEmpty ||
305
304
attachedFields.isNotEmpty ||
306
305
hostMethods.isNotEmpty;
307
306
308
- /// Whether the API has any message calls from host to Dart.
307
+ /// Whether the native type API makes any message calls to the Dart proxy
308
+ /// class or calls to instantiate a Dart proxy class instance.
309
309
bool hasAnyFlutterMessageCalls () =>
310
310
hasCallbackConstructor () || flutterMethods.isNotEmpty;
311
311
312
- /// Whether the host proxy API class will have methods that need to be
313
- /// implemented.
312
+ /// Whether the native type API will have methods that need to be implemented.
314
313
bool hasMethodsRequiringImplementation () =>
315
314
hasAnyHostMessageCalls () || unattachedFields.isNotEmpty;
316
315
@@ -407,7 +406,7 @@ class Constructor extends Method {
407
406
}
408
407
}
409
408
410
- /// Represents a field of an API .
409
+ /// Represents a field declared in a class denoted with the ProxyApi annotation .
411
410
class ApiField extends NamedType {
412
411
/// Constructor for [ApiField] .
413
412
ApiField ({
@@ -419,17 +418,17 @@ class ApiField extends NamedType {
419
418
this .isStatic = false ,
420
419
}) : assert (! isStatic || isAttached);
421
420
422
- /// Whether this is an attached field for a [AstProxyApi] .
421
+ /// Whether this represents an attached field of an [AstProxyApi] .
423
422
///
424
423
/// See [attached] .
425
424
final bool isAttached;
426
425
427
- /// Whether this is a static field of a [AstProxyApi] .
426
+ /// Whether this represents a static field of an [AstProxyApi] .
428
427
///
429
- /// A static field must also be attached. See [attached ] .
428
+ /// A static field must also be attached. See [static ] .
430
429
final bool isStatic;
431
430
432
- /// Returns a copy of [Parameter] instance with new attached [TypeDeclaration] .
431
+ /// Returns a copy of an [ApiField] with the new [TypeDeclaration] .
433
432
@override
434
433
ApiField copyWithType (TypeDeclaration type) {
435
434
return ApiField (
0 commit comments