wasm-bindgen/crates/macro/README.md

# `wasm-bindgen-macro`

Implementation of the `#[wasm_bindgen]` attribute. See the `wasm-bindgen`
documentation for more information about what this macro does.

## Testing

Testing of this macro is done through "ui tests" in the `ui-tests` subdirectory
of this crate. Each Rust file in this folder is compiled with the `wasm_bindgen`
crate, and the `*.stderr` file sitting next to it is the asserted output of the
compiler. If the output matches, the test passes, and if the output doesn't
match the test fails. Note that it is also considered a failure if a test
actually compiles successfully.

To add a test:

* Create `ui-tests/my-awesome-test.rs`
* Write an invalid `#[wasm_bindgen]` invocation, testing the error you're
  generating
* Execute `cargo test -p ui-tests`, the test will fail
* From within the `ui-tests` folder, execute `./update-all-references.sh`. This
  should create a `my-awesome-test.stderr` file.
* Inspect `my-awesome-test.stderr` to make sure it looks ok
* Rerun `cargo test -p ui-tests` and your tests should pass!

Testing here is a work in progress, see
[#601](https://github.com/rustwasm/wasm-bindgen/issues/601) for more
information.
Prepare to have targeted error diagnostics (#604) This commit starts to add infrastructure for targeted diagnostics in the `#[wasm_bindgen]` attribute, intended eventually at providing much better errors as they'll be pointing to exactly the code in question rather than always to a `#[wasm_bindgen]` attribute. The general changes are are: * A new `Diagnostic` error type is added to the backend. A `Diagnostic` is created with a textual error or with a span, and it can also be created from a list of diagnostics. A `Diagnostic` implements `ToTokens` which emits a bunch of invocations of `compile_error!` that will cause rustc to later generate errors. * Fallible implementations of `ToTokens` have switched to using a new trait, `TryToTokens`, which returns a `Result` to use `?` with. * The `MacroParse` trait has changed to returning a `Result` to propagate errors upwards. * A new `ui-tests` crate was added which uses `compiletest_rs` to add UI tests. These UI tests will verify that our output improves over time and does not regress. This test suite is added to CI as a new builder as well. * No `Diagnostic` instances are created just yet, everything continues to panic and return `Ok`, with the one exception of the top-level invocations of `syn::parse` which now create a `Diagnostic` and pass it along. This commit does not immediately improve diagnostics but the intention is that it is laying the groundwork for improving diagnostics over time. It should ideally be much easier to contribute improved diagnostics after this commit! cc #601 2018-08-02 01:15:27 +03:00			# `wasm-bindgen-macro`

			Implementation of the `#[wasm_bindgen]` attribute. See the `wasm-bindgen`
			`documentation for more information about what this macro does.`

			`## Testing`

			Testing of this macro is done through "ui tests" in the `ui-tests` subdirectory
			of this crate. Each Rust file in this folder is compiled with the `wasm_bindgen`
			crate, and the `*.stderr` file sitting next to it is the asserted output of the
			`compiler. If the output matches, the test passes, and if the output doesn't`
			`match the test fails. Note that it is also considered a failure if a test`
			`actually compiles successfully.`

			`To add a test:`

			* Create `ui-tests/my-awesome-test.rs`
			* Write an invalid `#[wasm_bindgen]` invocation, testing the error you're
			`generating`
			* Execute `cargo test -p ui-tests`, the test will fail
			* From within the `ui-tests` folder, execute `./update-all-references.sh`. This
			should create a `my-awesome-test.stderr` file.
			* Inspect `my-awesome-test.stderr` to make sure it looks ok
			* Rerun `cargo test -p ui-tests` and your tests should pass!

			`Testing here is a work in progress, see`
			`[#601](https://github.com/rustwasm/wasm-bindgen/issues/601) for more`
			`information.`