Add info on generation conventions (#171)

This makes it easier for users to determine why some APIs
are emitted the way they are.

Author: srujzs

README.md

@@ -25,6 +25,41 @@ void main() {
 }
 ```
 
+## Generation conventions
+
+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` 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
+
+- 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 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`.
+
+### 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:

tool/generator/bcd.dart

@@ -117,7 +117,7 @@ abstract class BCDItem {
 }
 
 extension BCDJsonDataExtension on Map<String, dynamic> {
-  /// 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<String> get symbolNames => keys.where((key) => !key.startsWith('_'));
 }