Add docs and doc comment for unstable APIs

Author: grovesNL

crates/backend/src/util.rs

@@ -158,15 +158,17 @@ impl<T: Hash> fmt::Display for ShortHash<T> {
 }
 
 
-/// Create a syn attribute for `#[cfg(web_sys_unstable_apis)]`.
-pub fn unstable_api_attr() -> syn::Attribute {
-    syn::parse_quote!( #[cfg(web_sys_unstable_apis)] )
+/// Create syn attribute for `#[cfg(web_sys_unstable_apis)]` and a doc comment.
+pub fn unstable_api_attrs() -> proc_macro2::TokenStream {
+    quote::quote!(
+        #[cfg(web_sys_unstable_apis)]
+        #[doc = "\n\n*This API is unstable and requires `--cfg=web_sys_unstable_apis` to be activated, as [described in the `wasm-bindgen` guide](https://rustwasm.github.io/docs/wasm-bindgen/web-sys/unstable-apis.html)*"]
+    )
 }
 
-
-pub fn maybe_unstable_api_attr(unstable_api: bool) -> Option<syn::Attribute> {
+pub fn maybe_unstable_api_attr(unstable_api: bool) -> Option<proc_macro2::TokenStream> {
     if unstable_api {
-        Some(unstable_api_attr())
+        Some(unstable_api_attrs())
     } else {
         None
     }

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
+```