From 2d5572edf79967f1fff6927a44983003e61cef02 Mon Sep 17 00:00:00 2001 From: Devon Carew Date: Mon, 4 Mar 2024 12:11:23 -0800 Subject: [PATCH 1/3] add instructions for re-generating the package --- README.md | 9 +++++---- tool/README.md | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0fb86065..7645e261 100644 --- a/README.md +++ b/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. diff --git a/tool/README.md b/tool/README.md index 798bc27c..2753b827 100644 --- a/tool/README.md +++ b/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. In order to re-generate the package, run: + +### 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: From b494fa082163c9acb8cfd31eea21e46b66071223 Mon Sep 17 00:00:00 2001 From: Devon Carew Date: Mon, 4 Mar 2024 12:12:44 -0800 Subject: [PATCH 2/3] edits --- tool/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tool/README.md b/tool/README.md index 2753b827..a9925a11 100644 --- a/tool/README.md +++ b/tool/README.md @@ -1,7 +1,7 @@ ## Updating the package This Dart code in this package is generated from Web IDL definitions and MDN API -documentation. In order to re-generate the package, run: +documentation. ### Regenerating the package From 3b70877c7e7c2a7a28aef37ab9093cdd0b2bb678 Mon Sep 17 00:00:00 2001 From: Devon Carew Date: Mon, 4 Mar 2024 12:40:28 -0800 Subject: [PATCH 3/3] minor updates --- tool/README.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/tool/README.md b/tool/README.md index a9925a11..91d0d1f9 100644 --- a/tool/README.md +++ b/tool/README.md @@ -1,11 +1,11 @@ ## Updating the package -This Dart code in this package is generated from Web IDL definitions and MDN API +The 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: +To regenerate the package from the current IDL versions, run: ```shell dart tool/update_bindings.dart @@ -13,18 +13,17 @@ dart tool/update_bindings.dart ### Updating the dartdoc info from MDN -The dartdoc comments come from the +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 this documentation, run: +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`. 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. +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