From 676611020e78fae84cd5bda17e01847aa4aa6566 Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Tue, 7 Aug 2018 13:23:00 -0700 Subject: [PATCH] guide: Delete "Feature Reference" page We now have a rather large section for feature reference, and I don't think there is anything in this page that isn't covered elsewhere and in more detail anymore. --- guide/src/SUMMARY.md | 1 - guide/src/reference/feature-reference.md | 51 ------------------------ guide/src/reference/passing-data.md | 10 ++--- 3 files changed, 5 insertions(+), 57 deletions(-) delete mode 100644 guide/src/reference/feature-reference.md diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 57246bd41..bd699f896 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -13,7 +13,6 @@ - [Receiving JS Closures in Rust](./reference/receiving-js-closures-in-rust.md) - [No ES Modules](./reference/no-esm.md) - [Passing Arbitrary data](./reference/passing-data.md) - - [Feature Reference](./reference/feature-reference.md) - [Command Line Interface](./reference/cli.md) - [Supported Types](./reference/types.md) - [`#[wasm_bindgen]` Attributes](./reference/attributes/index.md) diff --git a/guide/src/reference/feature-reference.md b/guide/src/reference/feature-reference.md deleted file mode 100644 index 53183ad96..000000000 --- a/guide/src/reference/feature-reference.md +++ /dev/null @@ -1,51 +0,0 @@ -# Feature Reference - -Here this section will attempt to be a reference for the various features -implemented in this project. This is likely not exhaustive but the [tests] -should also be a great place to look for examples. - -[tests]: https://github.com/rustwasm/wasm-bindgen/tree/master/tests - -The `#[wasm_bindgen]` attribute can be attached to functions, structs, -impls, and foreign modules. Impls can only contain functions, and the attribute -cannot be attached to functions in an impl block or functions in a foreign -module. No lifetime parameters or type parameters are allowed on any of these -types. Foreign modules must have the `"C"` abi (or none listed). Free functions -with `#[wasm_bindgen]` might not have the `"C"` abi or none listed, and it's also not -necessary to annotate with the `#[no_mangle]` attribute. - -All structs referenced through arguments to functions should be defined in the -macro itself. Arguments allowed implement the `WasmBoundary` trait, and examples -are: - -* Integers (u64/i64 require `BigInt` support) -* Floats -* Borrowed strings (`&str`) -* Owned strings (`String`) -* Exported structs (`Foo`, annotated with `#[wasm_bindgen]`) -* Exported C-like enums (`Foo`, annotated with `#[wasm_bindgen]`) -* Imported types in a foreign module annotated with `#[wasm_bindgen]` -* Borrowed exported structs (`&Foo` or `&mut Bar`) -* The `JsValue` type and `&JsValue` (not mutable references) -* Vectors and slices of supported integer types and of the `JsValue` type. -* Optional vectors/slices - -All of the above can also be returned except borrowed references. Passing -`Vec` as an argument to a function is not currently supported. Strings are -implemented with shim functions to copy data in/out of the Rust heap. That is, a -string passed to Rust from JS is copied to the Rust heap (using a generated shim -to malloc some space) and then will be freed appropriately. - -Owned values are implemented through boxes. When you return a `Foo` it's -actually turned into `Box>` under the hood and returned to JS as a -pointer. The pointer is to have a defined ABI, and the `RefCell` is to ensure -safety with reentrancy and aliasing in JS. In general you shouldn't see -`RefCell` panics with normal usage. - -JS-values-in-Rust are implemented through indexes that index a table generated -as part of the JS bindings. This table is managed via the ownership specified in -Rust and through the bindings that we're returning. More information about this -can be found in the [design doc]. - -All of these constructs currently create relatively straightforward code on the -JS side of things, mostly having a 1:1 match in Rust with JS. diff --git a/guide/src/reference/passing-data.md b/guide/src/reference/passing-data.md index c7e00c980..29a1dcf2e 100644 --- a/guide/src/reference/passing-data.md +++ b/guide/src/reference/passing-data.md @@ -1,7 +1,7 @@ # Passing arbitrary data to JS -It's possible to pass data from Rust to JS not explicitly supported -in the [Feature Reference](./feature-reference.md) by serializing via [Serde](https://github.com/serde-rs/serde). +It's possible to pass arbirtrary data from Rust to JavaScript by serializing it +with [Serde](https://github.com/serde-rs/serde). `wasm-bindgen` includes the `JsValue` type, which streamlines serializing and deserializing. @@ -20,7 +20,7 @@ features = ["serde-serialize"] ``` In our top-level Rust file (eg `lib.rs` or `main.rs`), we enable the `Serialize` -macro: +macro: ```rust #[macro_use] extern crate serde_derive; @@ -58,7 +58,7 @@ pub fn pass_example() -> JsValue { ``` When calling this function from JS, its output will automatically be deserialized. -In this example, `fied1` will be a JS `object` (Not a JS `Map`), `field2` will be a +In this example, `fied1` will be a JS `object` (Not a JS `Map`), `field2` will be a 2d JS `array`, and `field3` will be a 1d JS `array`. Example calling code: ```typescript @@ -69,4 +69,4 @@ rust.then( console.log(r.pass_example()) } ) -``` \ No newline at end of file +```