From ab571d0f4780de268afe3af2dd01f4da1127d5df Mon Sep 17 00:00:00 2001 From: Srujan Gaddam Date: Wed, 14 Feb 2024 17:51:09 -0800 Subject: [PATCH 1/2] Add info on generation conventions This makes it easier for users to determine why some APIs are emitted the way they are. --- README.md | 36 ++++++++++++++++++++++++++++++++++++ tool/generator/bcd.dart | 2 +- 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 880fecfe..12e96d72 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,42 @@ void main() { } ``` +## Generation conventions + +The generator scripts use a number of conventions they use consistently to +handle Web IDL definitions: + +### Interfaces + +- Interfaces are emitted as extension types that wrap and implement `JSObject`. +- Interface inheritance is maintained using `implements`. +- Members of partial interfaces and partial mixins are added to the interfaces + and mixins that include them, and therefore do not have separate declarations. +- Members of mixins are added to the interfaces that include them, and therefore + do not have separate declarations. + +### Types + +- Generic types include the generic in the case of `JSArray` and `JSPromise`. +- Enums are typedef'd to `String`. +- Callbacks and callback interfaces are typedef'd to `JSFunction`. +- In general, we prefer the Dart primitive over the JS type equivalent wherever + possible. For example, APIs use `String` instead of `JSString`. +- If a type appears in a generic position and it was typedef'd to a Dart + primitive type, it is replaced with the JS type equivalent to respect type + bounds. +- Union types are computed by picking the least upper bound of the types in the + JS type hierarchy, where every interface is equivalent to `JSObject`. + +### Compatibility + +- The generator uses the + [MDN compatibility data](https://github.com/mdn/browser-compat-data) to + determine what members and interfaces to emit. Currently, we only emit code + that is standards track and supported on Chrome, Firefox, and Safari to reduce + the number of breaking changes. This is currently WIP and some members may be + added or removed. + ## Web IDL version Based on: diff --git a/tool/generator/bcd.dart b/tool/generator/bcd.dart index ad7a19ff..3133a35d 100644 --- a/tool/generator/bcd.dart +++ b/tool/generator/bcd.dart @@ -117,7 +117,7 @@ abstract class BCDItem { } extension BCDJsonDataExtension on Map { - /// Return keys which coorespond to symbol names (i.e., filter out non-symbol + /// Return keys which correspond to symbol names (i.e., filter out non-symbol /// metadata (`__meta`, `__compat`, ...). Iterable get symbolNames => keys.where((key) => !key.startsWith('_')); } From 1975778d0ab508fbe6b1adf899a5d9bd0b445334 Mon Sep 17 00:00:00 2001 From: Srujan Gaddam Date: Thu, 15 Feb 2024 10:21:45 -0800 Subject: [PATCH 2/2] Address review comments --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 12e96d72..63ddf670 100644 --- a/README.md +++ b/README.md @@ -27,17 +27,16 @@ void main() { ## Generation conventions -The generator scripts use a number of conventions they use consistently to -handle Web IDL definitions: +The generator scripts use a number of conventions to consistently handle Web IDL +definitions: ### Interfaces - Interfaces are emitted as extension types that wrap and implement `JSObject`. -- Interface inheritance is maintained using `implements`. -- Members of partial interfaces and partial mixins are added to the interfaces - and mixins that include them, and therefore do not have separate declarations. -- Members of mixins are added to the interfaces that include them, and therefore - do not have separate declarations. +- Interface inheritance is maintained using `implements` between extension + types. +- Members of partial interfaces, partial mixins, and mixins are added to the + interfaces that include them, and therefore do not have separate declarations. ### Types @@ -47,8 +46,8 @@ handle Web IDL definitions: - In general, we prefer the Dart primitive over the JS type equivalent wherever possible. For example, APIs use `String` instead of `JSString`. - If a type appears in a generic position and it was typedef'd to a Dart - primitive type, it is replaced with the JS type equivalent to respect type - bounds. + primitive type, it is replaced with the JS type equivalent to respect the type + bound of `JSAny?`. - Union types are computed by picking the least upper bound of the types in the JS type hierarchy, where every interface is equivalent to `JSObject`.