add page to guide about enums

examples/guide-supported-types-examples/enum.js

@@ -0,0 +1,27 @@
+import {
+  take_number,
+  take_string,
+  take_number_option,
+  take_string_option,
+  return_number,
+  return_string,
+  return_number_option,
+  return_string_option,
+  NumberEnum,
+  // nothing generated for StringEnum :(
+} from "./guide_supported_types_examples";
+
+take_number(NumberEnum.Foo);
+take_string("spam");
+
+take_number_option(NumberEnum.Bar);
+take_number_option(undefined);
+
+take_string_option("eggs");
+take_string_option(undefined);
+
+return_number(); // typed as `NumberEnum`
+return_string(); // typed as `any`
+
+return_number_option(); // typed as `NumberEnum | undefined`
+return_string_option(); // typed as `any | undefined`

examples/guide-supported-types-examples/src/enums.rs

@@ -0,0 +1,47 @@
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub enum NumberEnum {
+    // numbers are optional; default ones will be generated if not provided
+    Foo = 0,
+    Bar = 1,
+    Baz = 2,
+}
+
+#[wasm_bindgen]
+pub enum StringEnum {
+    Spam = "spam",
+    Eggs = "eggs",
+}
+
+#[wasm_bindgen]
+pub fn take_number(x: NumberEnum) {}
+
+#[wasm_bindgen]
+pub fn take_string(x: StringEnum) {}
+
+#[wasm_bindgen]
+pub fn take_number_option(x: Option<NumberEnum>) {}
+
+#[wasm_bindgen]
+pub fn take_string_option(x: Option<StringEnum>) {}
+
+#[wasm_bindgen]
+pub fn return_number() -> NumberEnum {
+    todo!()
+}
+
+#[wasm_bindgen]
+pub fn return_string() -> StringEnum {
+    todo!()
+}
+
+#[wasm_bindgen]
+pub fn return_number_option() -> Option<NumberEnum> {
+    todo!()
+}
+
+#[wasm_bindgen]
+pub fn return_string_option() -> Option<StringEnum> {
+    todo!()
+}

examples/guide-supported-types-examples/src/lib.rs

@@ -4,6 +4,7 @@ pub mod bool;
 pub mod boxed_js_value_slice;
 pub mod boxed_number_slices;
 pub mod char;
+pub mod enums;
 pub mod exported_types;
 pub mod imported_types;
 pub mod js_value;

guide/src/SUMMARY.md

@@ -2,7 +2,7 @@
 
 [Introduction](./introduction.md)
 
---------------------------------------------------------------------------------
+---
 
 - [Examples](./examples/index.md)
   - [Hello, World!](./examples/hello-world.md)
@@ -32,6 +32,7 @@
   - [Wasm Audio Worklet](./examples/wasm-audio-worklet.md)
   - [web-sys: A TODO MVC App](./examples/todomvc.md)
 - [Reference](./reference/index.md)
+
   - [Deployment](./reference/deployment.md)
   - [JS snippets](./reference/js-snippets.md)
   - [Static JS Objects](./reference/static-js-objects.md)
@@ -59,6 +60,7 @@
     - [`char`](./reference/types/char.md)
     - [`str`](./reference/types/str.md)
     - [`String`](./reference/types/string.md)
+    - [`enum`](./reference/types/enum.md)
     - [Number Slices](./reference/types/number-slices.md)
     - [Boxed Number Slices](./reference/types/boxed-number-slices.md)
     - [`Result<T, E>`](./reference/types/result.md)
@@ -98,6 +100,7 @@
       - [`getter_with_clone`](./reference/attributes/on-rust-exports/getter_with_clone.md)
 
 - [`web-sys`](./web-sys/index.md)
+
   - [Using `web-sys`](./web-sys/using-web-sys.md)
   - [Cargo Features](./web-sys/cargo-features.md)
   - [Function Overloads](./web-sys/function-overloads.md)
@@ -106,6 +109,7 @@
   - [Unstable APIs](./web-sys/unstable-apis.md)
 
 - [Testing with `wasm-bindgen-test`](./wasm-bindgen-test/index.md)
+
   - [Usage](./wasm-bindgen-test/usage.md)
   - [Writing Asynchronous Tests](./wasm-bindgen-test/asynchronous-tests.md)
   - [Testing in Headless Browsers](./wasm-bindgen-test/browsers.md)

guide/src/reference/types/enum.md

@@ -0,0 +1,72 @@
+# enum
+
+| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |
+| :-----------: | :------------: | :----------------: | :--------------: | :-------------------: | :----------------------: | :-----------------------: |
+|      Yes      |       No       |         No         |        No        |          Yes          |           Yes            |   `string` or `number`    |
+
+## Example Rust Usage
+
+```rust
+{{#include ../../../../examples/guide-supported-types-examples/src/enum.rs}}
+```
+
+## Example JavaScript Usage
+
+```js
+{{#include ../../../../examples/guide-supported-types-examples/enum.js}}
+```
+
+## TypeScript
+
+Unfortunately, string enums don't fully work yet; no TypeScript is generated for the enum itself and functions using them accept or return `any`.
+They work correctly, it's just there's no type hints.
+See [Issue #3057](https://github.com/rustwasm/wasm-bindgen/issues/3057)
+
+The generated TypeScript declarations for the above:
+
+<!-- remember to keep this up to date! copy enum.rs (above) into the lib.rs file of a new wasm-bindgen crate; use `wasm-pack build`; then copy pkg/testcrate.d.ts. also ran it through a formatter. -->
+
+```ts
+/**
+ * @param {NumberEnum} x
+ */
+export function take_number(x: NumberEnum): void;
+/**
+ * @param {any} x
+ */
+export function take_string(x: any): void;
+/**
+ * @param {NumberEnum | undefined} [x]
+ */
+export function take_number_option(x?: NumberEnum): void;
+/**
+ * @param {any | undefined} [x]
+ */
+export function take_string_option(x?: any): void;
+/**
+ * @returns {NumberEnum}
+ */
+export function return_number(): NumberEnum;
+/**
+ * @returns {any}
+ */
+export function return_string(): any;
+/**
+ * @returns {NumberEnum | undefined}
+ */
+export function return_number_option(): NumberEnum | undefined;
+/**
+ * @returns {any | undefined}
+ */
+export function return_string_option(): any | undefined;
+/**
+ */
+export enum NumberEnum {
+  Foo = 0,
+  Bar = 1,
+  Baz = 2,
+}
+
+// no types generated for StringEnum (yet) :(
+// see the note above
+```