add instructions for re-generating the package (#195)

* add instructions for re-generating the package

* edits

* minor updates

Author: devoncarew

README.md

@@ -67,8 +67,9 @@ definitions:
   the number of breaking changes. This is currently WIP and some members may be
   added or removed.
 
-## Generation
+## Generation and updating the package
 
-Most of the APIs in this package are generated from public assets. See the
-[tool directory](https://github.com/dart-lang/web/tree/main/tool) in the source
-repository to learn more.
+Most of the APIs in this package are generated from public assets. See
+[tool/README.md](https://github.com/dart-lang/web/tree/main/tool) for
+information on the spec and IDL versions the package was generated from, and for
+the process for updating the package.

tool/README.md

@@ -1,3 +1,41 @@
+## Updating the package
+
+The Dart code in this package is generated from Web IDL definitions and MDN API
+documentation.
+
+### Regenerating the package
+
+To regenerate the package from the current IDL versions, run:
+
+```shell
+dart tool/update_bindings.dart
+```
+
+### Updating the dartdoc info from MDN
+
+package:web's dartdoc comments come from the
+[MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web) project. In order
+to update to the latest version of the documentation, run:
+
+```shell
+dart tool/scrape_mdn.dart
+```
+
+That will collect the MDN documentation into `third_party/mdn/mdn.json`; changes
+to that file should be committed to git. You'll need to run
+`tool/update_bindings.dart` to produce Dart code using the updated documentation.
+
+### Updating to use the latest Web IDL versions
+
+To re-generate the package from newer IDL versions, you can either run:
+
+```shell
+dart tool/update_bindings.dart --update
+```
+
+or, edit manually edit `tool/generator/package.json` to use specific IDL
+versions, and re-run `tool/update_bindings.dart`.
+
 ## Web IDL versions
 
 Based on: