From f881640d3d6c8c7adbf14914e10fd5dee2a0536f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= <ged@odoo.com>
Date: Fri, 7 Jun 2019 15:47:04 +0200
Subject: [PATCH] [DOC] event_bus: add initial doc

closes #157
---
 doc/event_bus.md | 27 +++++++++++++++++++++++++++
 doc/readme.md    |  1 +
 doc/store.md     |  2 +-
 3 files changed, 29 insertions(+), 1 deletion(-)
 create mode 100644 doc/event_bus.md

diff --git a/doc/event_bus.md b/doc/event_bus.md
new file mode 100644
index 00000000..d339c0d7
--- /dev/null
+++ b/doc/event_bus.md
@@ -0,0 +1,27 @@
+# 🦉 Event Bus 🦉
+
+It is sometimes useful to use a `Bus` to communicate informations between various
+parts of the code. Owl has a very simple bus class, which manages subscriptions,
+triggering events, and callbacks.
+
+```js
+const bus = new owl.EventBus();
+
+bus.on("some-event", null, function(...args) {
+  console.log(...args);
+});
+
+bus.trigger("some-event", 1, 2, 3);
+// [1,2,3] will be logged to the console
+```
+
+Its API is:
+
+| Method                           | Description                       |
+| -------------------------------- | --------------------------------- |
+| `on(eventType, owner, callback)` | add a listener                    |
+| `off(eventType, owner)`          | remove all listeners for an owner |
+| `trigger(eventType, ...args)`    | trigger an event                  |
+| `clear`                          | remove all subscriptions          |
+
+Note that the [`Store`](store.md) is an example of an `EventBus`.
diff --git a/doc/readme.md b/doc/readme.md
index 7aa494f3..dc5d5ebe 100644
--- a/doc/readme.md
+++ b/doc/readme.md
@@ -7,6 +7,7 @@
 - [QWeb](qweb.md)
 - [Store](store.md)
 - [Observer](observer.md)
+- [Event Bus](event_bus.md)
 - [Virtual DOM](vdom.md)
 - [Utils](utils.md)
 
diff --git a/doc/store.md b/doc/store.md
index 8dc0011e..ae15c2de 100644
--- a/doc/store.md
+++ b/doc/store.md
@@ -63,7 +63,7 @@ store.dispatch('addTodo', 'fix all bugs');
 
 ## Reference
 
-The store is a simple `owl.EventBus` that triggers `update` events whenever its
+The store is a simple [`owl.EventBus`](event_bus.md) that triggers `update` events whenever its
 state is changed.  Note that these events are triggered only after a microtask
 tick, so only one event will be triggered for any number of state changes in a
 call stack.