From 00bb6736e305be4205a8ef6ce9945ee3f3335fad Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Thu, 26 Jul 2018 17:56:55 -0700
Subject: [PATCH] Add guide documentation for the `js-sys` crate (#566)

---
 guide/src/SUMMARY.md                 |  3 ++
 guide/src/js-sys.md                  | 51 ++++++++++++++++++++++++++++
 guide/src/js-sys/adding-more-apis.md | 26 ++++++++++++++
 guide/src/js-sys/testing.md          | 13 +++++++
 4 files changed, 93 insertions(+)
 create mode 100644 guide/src/js-sys.md
 create mode 100644 guide/src/js-sys/adding-more-apis.md
 create mode 100644 guide/src/js-sys/testing.md

diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md
index fe383512..7c41dff6 100644
--- a/guide/src/SUMMARY.md
+++ b/guide/src/SUMMARY.md
@@ -27,6 +27,9 @@
     - [Customizing imports](./design/import-customization.md)
     - [Rust Type conversions](./design/rust-type-conversions.md)
     - [Types in `wasm-bindgen`](./design/describe.md)
+  - [`js-sys`](./js-sys.md)
+    - [Testing](./js-sys/testing.md)
+    - [Adding More APIs](./js-sys/adding-more-apis.md)
   - [`web-sys`](./web-sys.md)
     - [Overview](./web-sys/overview.md)
     - [Testing](./web-sys/testing.md)
diff --git a/guide/src/js-sys.md b/guide/src/js-sys.md
new file mode 100644
index 00000000..57f0b217
--- /dev/null
+++ b/guide/src/js-sys.md
@@ -0,0 +1,51 @@
+# `js-sys`
+
+The [`js-sys` crate][js-sys] provides raw bindings to all the global APIs
+guaranteed to exist in every JavaScript environment by the ECMAScript standard,
+and its source lives at [`wasm-bindgen/crates/js-sys`][src].  With the `js-sys`
+crate, we can work with `Object`s, `Array`s, `Function`s, `Map`s, `Set`s,
+etc... without writing the `#[wasm_bindgen]` imports by hand.
+
+Documentation for this crate will eventually be available on [docs.rs][docsrs]
+but temporarily you can also check out the [master branch
+documentation][masterdoc] for the crate.
+
+[docsrs]: https://docs.rs/js-sys
+[masterdoc]: https://rustwasm.github.io/wasm-bindgen/api/js_sys/
+[src]: https://github.com/rustwasm/wasm-bindgen/tree/master/crates/js-sys
+
+For example, we can invoke JavaScript [`Function`][mdn-function] callbacks and
+time how long they take to execute with [`Date.now()`][mdn-date-now], and we
+don't need to write any JS imports ourselves:
+
+```rust
+extern crate js_sys;
+extern crate wasm_bindgen;
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn timed(callback: &js_sys::Function) -> f64 {
+    let then = js_sys::Date::now();
+    callback.apply(JsValue::null(), &js_sys::Array::new()).unwrap();
+    let now = js_sys::Date::now();
+    now - then
+}
+```
+
+The `js-sys` crate isn't quite 100% feature complete yet. There are still some
+JavaScript types and methods that we don't have bindings for. If you'd like to
+help out check out [the contribution documentation][contrib].
+
+Also, as mentioned above, the `js-sys` crate doesn't contain bindings to any Web
+APIs like [`document.querySelectorAll`][mdn-qsa]. These will be part of the
+[`web-sys`](./web-sys.html) crate.
+
+[MDN]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects
+[js-sys]: https://crates.io/crates/js-sys
+[issue]: https://github.com/rustwasm/wasm-bindgen/issues/275
+[mdn-function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
+[mdn-qsa]: https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll
+[web-sys-contributing]: https://rustwasm.github.io/wasm-bindgen/web-sys.html
+[web-sys-issues]: https://github.com/rustwasm/wasm-bindgen/issues?q=is%3Aissue+is%3Aopen+label%3Aweb-sys
+[mdn-date-now]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now
+[contrib]: https://github.com/rustwasm/wasm-bindgen/issues/275
diff --git a/guide/src/js-sys/adding-more-apis.md b/guide/src/js-sys/adding-more-apis.md
new file mode 100644
index 00000000..4c77bd50
--- /dev/null
+++ b/guide/src/js-sys/adding-more-apis.md
@@ -0,0 +1,26 @@
+# Adding more APIs
+
+We've got a [GitHub issue][issue] tracking the remaining APIs that need to be
+added to the `js-sys` crate, and we'd love your help in contributing! The steps
+to follow are:
+
+* Comment on the issue saying which thing you are going to make bindings for
+  (so that we don't accidentally duplicate effort).
+
+* Open the [MDN
+  page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects)
+  for the relevant JS API.
+
+* Open `crates/js-sys/src/lib.rs` in your editor; this is the file where we are
+  implementing the bindings.
+
+* Follow the instructions in the top of `crates/js-sys/src/lib.rs` about how to
+  add new bindings.
+
+* Add a test for the new binding to `crates/js-sys/tests/wasm/MyType.rs`
+
+* Run the JS global API bindings tests with `cargo test -p js-sys --target wasm32-unknown-unknown`
+
+* Send a pull request!
+
+[issue]: https://github.com/rustwasm/wasm-bindgen/issues/275
diff --git a/guide/src/js-sys/testing.md b/guide/src/js-sys/testing.md
new file mode 100644
index 00000000..1ff0e6a4
--- /dev/null
+++ b/guide/src/js-sys/testing.md
@@ -0,0 +1,13 @@
+# Testing
+
+You can test the `js-sys` crate by running `cargo test --target
+wasm32-unknown-unknown` within the `crates/web-sys` directory in the
+`wasm-bindgen` repository:
+
+```sh
+cd wasm-bindgen/crates/web-sys
+cargo test --target wasm32-unknown-unknown
+```
+
+These tests are largely executed in Node.js right now via the
+`wasm-bindgen-test` framework. More documentation on the framework coming soon!