From cb339513c33a876bcba9a78e8b02cb2be293b07c Mon Sep 17 00:00:00 2001
From: Oscar Beaumont <oscar@otbeaumont.me>
Date: Tue, 30 Apr 2024 22:15:43 +0800
Subject: [PATCH] Update v2 docs

---
 docs/v2.md | 82 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 69 insertions(+), 13 deletions(-)

diff --git a/docs/v2.md b/docs/v2.md
index 127e948..81a00d6 100644
--- a/docs/v2.md
+++ b/docs/v2.md
@@ -69,20 +69,20 @@ use tauri_specta::{ts, js};
 // this example exports your types on startup when in debug mode. You can do whatever.
 
 fn main() {
-    let specta_builder = {
+    let invoke_handler = {
         // You can use `tauri_specta::js::builder` for exporting JS Doc instead of Typescript!`
-        let specta_builder = tauri_specta::ts::builder()
-            .commands(tauri_specta::collect_commands![greet, greet2, greet3 ]); // <- Each of your comments
+        let builder = tauri_specta::ts::builder()
+            .commands(tauri_specta::collect_commands![greet, greet2, greet3 ]); // <- Each of your commands
 
 
         #[cfg(debug_assertions)] // <- Only export on non-release builds
-        let specta_builder = specta_builder.path("../src/bindings.ts");
+        let builder = builder.path("../src/bindings.ts");
 
-        specta_builder.into_plugin()
+        builder.build().unwrap()
     };
 
     tauri::Builder::default()
-        .plugin(specta_builder)
+        .invoke_handler(invoke_handler)
         .run(tauri::generate_context!())
         .expect("error while running tauri application");
 }
@@ -98,24 +98,50 @@ await commands.greet("Brendan");
 
 ## Events
 
-Firstly you have to define your event types. You can add as many of these as you want.
+You must reconfigure your builder to support events:
+
+```diff
+fn main() {
+-    let invoke_handler = {
++    let (invoke_handler, register_events) = {
+        // You can use `tauri_specta::js::builder` for exporting JS Doc instead of Typescript!`
+        let builder = tauri_specta::ts::builder()
+            .commands(tauri_specta::collect_commands![greet, greet2, greet3 ]) // <- Each of your commands
++           .events(tauri_specta::collect_events![]); // This should contain all your events.
+
+        #[cfg(debug_assertions)] // <- Only export on non-release builds
+        let builder = builder.path("../src/bindings.ts");
+
+        builder.build().unwrap()
+    };
+
+    tauri::Builder::default()
+        .invoke_handler(invoke_handler)
++       .setup(|app| {
++           register_events(app);
++       })
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+Now you can add your first event. You can add as many of these as your want.
 
 ```rust
 #[derive(Debug, Clone, Serialize, Deserialize, specta::Type, tauri_specta::Event)]
 pub struct DemoEvent(String);
 ```
 
-Next you must add it to the builder like the following:
-
+and make sure you register the event with Tauri Specta by adding it to the `collect_events` macro like the following:
 ```rust
-let specta_builder = ts::builder()
-        .events(tauri_specta::collect_events![DemoEvent]); // This should contain all your events.
+.events(tauri_specta::collect_events![DemoEvent]); // This should contain all your events, comma separated.
 ```
 
-Then it can be used in Rust like the following:
+Finally, you can setup a listener or emit a message from Rust like the following:
 
 ```rust
 tauri::Builder::default()
+    .invoke_handler(invoke_handler)
     .setup(|app| {
         let handle = app.handle();
 
@@ -124,9 +150,19 @@ tauri::Builder::default()
         });
 
         DemoEvent("Test".to_string()).emit_all(&handle).unwrap();
-    });
+    })
+    ...
 ```
 
+Most methods take a `handle` which can be any of the following types:
+ - [`App`](https://docs.rs/tauri/2.0.0-beta.16/tauri/struct.App.html)
+ - [`AppHandle`](https://docs.rs/tauri/2.0.0-beta.16/tauri/struct.AppHandle.html)
+ - [`Webview`](https://docs.rs/tauri/2.0.0-beta.16/tauri/webview/struct.Webview.html)
+ - [`WebviewWindow`](https://docs.rs/tauri/2.0.0-beta.16/tauri/webview/struct.WebviewWindow.html)
+ - [`Window`](https://docs.rs/tauri/2.0.0-beta.16/tauri/window/struct.Window.html)
+
+The [`Event`](https://docs.rs/tauri-specta/latest/tauri_specta/trait.Event.html) trait defines all methods that can be used to emit or listen so refer to it.
+
 and it can be used in TS like the following:
 
 ```ts
@@ -145,3 +181,23 @@ await events.demoEvent.emit("Test")
 // Emit to a window
 await events.demoEvent(appWindow).emit("Test")
 ```
+
+## Extra Types
+
+Sometimes you might want to export a type to Typescript but it doesn't actually show up in any of our commands.
+
+You can do that like the following:
+
+```rust
+let builder = ts::builder()
+    // < your commands and events are probally here
+    .types(TypeCollection::default().register::<Custom>()); // < call `register` as much as you want.
+```
+
+`register` only supports [named types](https://docs.rs/specta/2.0.0-rc.11/specta/type/trait.NamedType.html) as otherwise you would run into the following problem:
+```rust
+//     vvv      - What would this be without a name?
+export ... = {};
+```
+
+Any type implemented using the [`Type`](https://docs.rs/specta/latest/specta/derive.Type.html) derive macro will meet this requirement.