add instructions for re-generating the package

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,42 @@
+## Updating the package
+
+This Dart code in this package is generated from Web IDL definitions and MDN API
+documentation.
+
+### Regenerating the package
+
+To regenerate the Dart code from the current IDL versions, run:
+
+```shell
+dart tool/update_bindings.dart
+```
+
+### Updating the dartdoc info from MDN
+
+The 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 this documentation, run:
+
+```shell
+dart tool/scrape_mdn.dart
+```
+
+That will collect the MDN documentation into `third_party/mdn/mdn.json`. Running
+the above command will update the mdn.json file; those changes 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: