[WIP] Add support for unstable WebIDL (#1997)

* Re-enable WebGPU WebIDL as experimental

* Add `web_sys_unstable_apis` attribute

* Add test for unstable WebIDL

* Include unstable WebIDL in docs.rs builds

* Add docs and doc comment for unstable APIs

* Add unstable API checks to CI

guide/src/SUMMARY.md

@@ -88,6 +88,7 @@
   - [Function Overloads](./web-sys/function-overloads.md)
   - [Type Translations](./web-sys/type-translations.md)
   - [Inheritance](./web-sys/inheritance.md)
+  - [Unstable APIs](./web-sys/unstable-apis.md)
 
 - [Testing with `wasm-bindgen-test`](./wasm-bindgen-test/index.md)
   - [Usage](./wasm-bindgen-test/usage.md)

guide/src/web-sys/unstable-apis.md

@@ -0,0 +1,31 @@
+# Unstable APIs
+
+It's common for browsers to implement parts of a web API while the specification
+for that API is still being written. The API may require frequent changes as the
+specification continues to be developed, so the WebIDL is relatively unstable.
+
+This causes some challenges for `web-sys` because it means `web-sys` would have
+to make breaking API changes whenever the WebIDL changes. It also means that
+previously published `web-sys` versions would be invalid, because the browser
+API may have been changed to match the updated WebIDL.
+
+To avoid frequent breaking changes for unstable APIs, `web-sys` hides all
+unstable APIs through an attribute that looks like:
+
+```rust
+#[cfg(web_sys_unstable_apis)]
+pub struct Foo;
+```
+
+By hiding unstable APIs through an attribute, it's necessary for crates to
+explicitly opt-in to these reduced stability guarantees in order to use these
+APIs. Specifically, these APIs do not follow semver and may break whenever the
+WebIDL changes.
+
+Crates can opt-in to unstable APIs at compile-time by passing the `cfg` flag
+`web_sys_unstable_apis`. Typically the `RUSTFLAGS` environment variable is used
+to do this. For example:
+
+```bash
+RUSTFLAGS=--cfg=web_sys_unstable_apis cargo run
+```