From 764f71c30d7abdae8d36ad7cce9fa44c5e0e76d9 Mon Sep 17 00:00:00 2001
From: pngwn <pnda007@gmail.com>
Date: Mon, 29 Apr 2019 23:17:14 +0100
Subject: [PATCH] Site: Document createEventDispatcher. (#2583)

---
 site/content/docs/02-template-syntax.md |  6 +++++
 site/content/docs/03-run-time.md        | 33 ++++++++++++++++++++++++-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index 260c3482d9..d573823402 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -366,7 +366,13 @@ Components can emit events using [createEventDispatcher](docs#createEventDispatc
 <SomeComponent on:whatever={handler}/>
 ```
 
+---
+
+As with DOM events, if the `on:` directive is used without a value, the component will *forward* the event, meaning that a consumer of the component can listen for it.
 
+```html
+<SomeComponent on:whatever/>
+```
 
 ### Element bindings
 
diff --git a/site/content/docs/03-run-time.md b/site/content/docs/03-run-time.md
index 0876cf3a36..6eae0094e9 100644
--- a/site/content/docs/03-run-time.md
+++ b/site/content/docs/03-run-time.md
@@ -176,8 +176,39 @@ Retrieves the context that belongs to the closest parent component with the spec
 
 #### `createEventDispatcher`
 
-TODO
+```js
+dispatch: ((name: string, detail?: any) => void) = createEventDispatcher();
+```
+
+---
+
+Creates an event dispatcher that can be used to dispatch [component events](docs#Component_events). Event dispatchers are functions that can take two arguments: `name` and `detail`.
+
+Component events created with `createEventDispatcher` create a [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent). These events do not [bubble](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#Event_bubbling_and_capture) and are not cancellable with `event.preventDefault()`. The `detail` argument corresponds to the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) property and can contain any type of data.
+
+```html
+<script>
+	import { createEventDispatcher } from 'svelte';
+
+	const dispatch = createEventDispatcher();
+</script>
 
+<button on:click="{() => dispatch('notify', 'detail value')}">Fire Event</button>
+```
+
+---
+
+Events dispatched from child components can be listened to in their parent. Any data provided when the event was dispatched is available on the `detail` property of the event object.
+
+```html
+<script>
+	function callbackFunction(event) {
+		console.log(`Notify fired! Detail: ${event.detail}`)
+	}
+</script>
+
+<Child on:notify="{callbackFunction}"/>
+```
 
 ### `svelte/store`