docs: move examples out of code into docs

docs/guides/components.md

@@ -7,6 +7,13 @@ The architecture of the Video.js player is centered around components. The `Play
 * [What is a Component?](#what-is-a-component)
 * [Creating a Component](#creating-a-component)
 * [Component Children](#component-children)
+  * [Basic Example](#basic-example)
+  * [Using Options](#using-options)
+* [Event Listening](#event-listening)
+  * [using on](#using-on)
+  * [Using off](#using-off)
+  * [Using one](#using-one)
+  * [Using trigger](#using-trigger)
 * [Default Component Tree](#default-component-tree)
 * [Specific Component Details](#specific-component-details)
   * [Progress Control](#progress-control)
@@ -36,8 +43,42 @@ In addition, there are a couple methods worth recognizing:
 * `videojs.registerComponent(String name, Function Comp)`: Registers component constructors with Video.js.
 * `videojs.extend(Function component, Object properties)`: Provides prototype inheritance. Can be used to extend a component's constructor, returning a new constructor with the given properties.
 
+Creation:
+
+```js
+// adding a button to the player
+var player = videojs('some-video-id');
+var Component = videojs.getComponent('Component');
+var button = new Component(player);
+
+console.log(button.el());
+```
+
+The above code will output
+
+```html
+<div class="video-js">
+  <div class="vjs-button">Button</div>
+</div>
+```
+
+Adding the new button to the player
+
+```js
+// adding a button to the player
+var player = videojs('some-video-id');
+var button = player.addChild('button');
+
+console.log(button.el());
+// will have the same html result as the previous example
+```
+
 ## Component Children
 
+Again, refer to [the component API docs](http://docs.videojs.com/docs/api/component.html) for complete details on methods available for managing component structures.
+
+### Basic Example
+
 When child component is added to a parent component, Video.js inserts the element of the child into the element of the parent. For example, adding a component like this:
 
 ```js
@@ -69,7 +110,174 @@ Results in a DOM that looks like this:
 </div>
 ```
 
-Again, refer to [the component API docs](http://docs.videojs.com/docs/api/component.html) for complete details on methods available for managing component structures.
+### Using Options
+
+Pass in options for child constructors and options for children of the child.
+
+```js
+var player = videojs('some-vid-id');
+var Component = videojs.getComponent('Component');
+var myComponent = new Component(player);
+var myButton = myComponent.addChild('MyButton', {
+  text: 'Press Me',
+  buttonChildExample: {
+    buttonChildOption: true
+  }
+});
+```
+
+Children can also be added via options when a component is initialized.
+
+> Note: Include a 'name' key which will be used if two child components of the same
+>       type that need different options.
+
+```js
+// MyComponent is from the above example
+var myComp = new MyComponent(player, {
+  children: ['button', {
+    name: 'button',
+    someOtherOption: true
+  }, {
+    name: 'button',
+    someOtherOption: false
+  }]
+});
+```
+
+## Event Listening
+
+### Using `on`
+
+```js
+var player = videojs('some-player-id');
+var Component = videojs.getComponent('Component');
+var myComponent = new Component(player);
+var myFunc = function() {
+  var myComponent = this;
+  console.log('myFunc called');
+};
+
+myComponent.on('eventType', myFunc);
+myComponent.trigger('eventType');
+// logs 'myFunc called'
+```
+
+The context of `myFunc` will be `myComponent` unless it is bound. You can add
+a listener to another element or component.
+
+```js
+var otherComponent = new Component(player);
+
+// myComponent/myFunc is from the above example
+myComponent.on(otherComponent.el(), 'eventName', myFunc);
+myComponent.on(otherComponent, 'eventName', myFunc);
+
+otherComponent.trigger('eventName');
+// logs 'myFunc called' twice
+```
+
+### Using `off`
+
+```js
+var player = videojs('some-player-id');
+var Component = videojs.getComponent('Component');
+var myComponent = new Component(player);
+var myFunc = function() {
+  var myComponent = this;
+  console.log('myFunc called');
+};
+myComponent.on('eventType', myFunc);
+myComponent.trigger('eventType');
+// logs 'myFunc called'
+
+myComponent.off('eventType', myFunc);
+myComponent.trigger('eventType');
+// does nothing
+```
+
+If myFunc gets excluded, *all* listeners for the event type will get removed. If
+eventType gets excluded, *all* listeners will get removed from the component.
+You can use `off` to remove listeners that get added to other elements or
+components using:
+
+ `myComponent.on(otherComponent...`
+
+In this case both the event type and listener function are **REQUIRED**.
+
+```js
+var otherComponent = new Component(player);
+
+// myComponent/myFunc is from the above example
+myComponent.on(otherComponent.el(), 'eventName', myFunc);
+myComponent.on(otherComponent, 'eventName', myFunc);
+
+otherComponent.trigger('eventName');
+// logs 'myFunc called' twice
+myComponent.off(ootherComponent.el(), 'eventName', myFunc);
+myComponent.off(otherComponent, 'eventName', myFunc);
+otherComponent.trigger('eventName');
+// does nothing
+```
+
+### Using `one`
+
+```js
+var player = videojs('some-player-id');
+var Component = videojs.getComponent('Component');
+var myComponent = new Component(player);
+var myFunc = function() {
+  var myComponent = this;
+  console.log('myFunc called');
+};
+myComponent.one('eventName', myFunc);
+myComponent.trigger('eventName');
+// logs 'myFunc called'
+
+myComponent.trigger('eventName');
+// does nothing
+```
+
+You can also add a listener to another element or component that will get
+triggered only once.
+
+```js
+var otherComponent = new Component(player);
+
+// myComponent/myFunc is from the above example
+myComponent.one(otherComponent.el(), 'eventName', myFunc);
+myComponent.one(otherComponent, 'eventName', myFunc);
+
+otherComponent.trigger('eventName');
+// logs 'myFunc called' twice
+
+otherComponent.trigger('eventName');
+// does nothing
+```
+
+### Using `trigger`
+
+```js
+var player = videojs('some-player-id');
+var Component = videojs.getComponent('Component');
+var myComponent = new Component(player);
+var myFunc = function(data) {
+  var myComponent = this;
+  console.log('myFunc called');
+  console.log(data);
+};
+myComponent.one('eventName', myFunc);
+myComponent.trigger('eventName');
+// logs 'myFunc called' and 'undefined'
+
+myComponent.trigger({'type':'eventName'});
+// logs 'myFunc called' and 'undefined'
+
+myComponent.trigger('eventName', {data: 'some data'});
+// logs 'myFunc called' and "{data: 'some data'}"
+
+myComponent.trigger({'type':'eventName'}, {data: 'some data'});
+// logs 'myFunc called' and "{data: 'some data'}"
+```
 
 ## Default Component Tree
 

docs/guides/event-target.md

@@ -0,0 +1,118 @@
+# Event Target
+
+## Table of Contents
+
+* [Overview](#overview)
+* [on() and addEventListener()](#on-and-addeventlistener)
+* [off() and removeEventListener](#off-and-removeeventlistener)
+* [one()](#one)
+* [trigger() and dispatchEvent](#trigger-and-dispatchevent)
+
+## Overview
+
+Events in video.js are setup so that they mimic the DOM API that is used on object, but also have helpful shorthand functions with the same functionality.
+
+## `on()` and `addEventListener()`
+
+This function is used to add an event listener to an EventTarget.
+
+```js
+var foo = new EventTarget();
+var handleBar = function() {
+  console.log('bar was triggered');
+};
+
+foo.on('bar', handleBar);
+
+// This causes any `event listeners` for the `bar` event to get called
+// see {@link EventTarget#trigger} for more information
+foo.trigger('bar');
+// logs 'bar was triggered'
+```
+
+## `off()` and `removeEventListener()`
+
+This function is used to remove an listener function from an EventTarget.
+
+```js
+var foo = new EventTarget();
+var handleBar = function() {
+  console.log('bar was triggered');
+};
+
+// adds an `event listener` for the `bar` event
+// see {@link EventTarget#on} for more info
+foo.on('bar', handleBar);
+
+// runs all `event listeners` for the `bar` event
+// see {@link EventTarget#trigger} for more info
+foo.trigger('bar');
+// logs 'bar was triggered'
+
+foo.off('bar', handleBar);
+foo.trigger('bar');
+// does nothing
+```
+
+## `one()`
+
+This function is used to only have an event listener called once and never again.
+
+Using `on()` and `off()` to mimic `one()` (not recommended)
+
+```js
+var foo = new EventTarget();
+var handleBar = function() {
+  console.log('bar was triggered');
+  // after the first trigger remove this handler
+  foo.off('bar', handleBar);
+};
+
+foo.on('bar', handleBar);
+foo.trigger('bar');
+// logs 'bar was triggered'
+
+foo.trigger('bar');
+// does nothing
+```
+
+Using `one()`
+
+```js
+var foo = new EventTarget();
+var handleBar = function() {
+  console.log('bar was triggered');
+};
+
+// removed after the first trigger
+foo.one('bar', handleBar);
+foo.trigger('bar');
+// logs 'bar was triggered'
+
+foo.trigger('bar');
+// does nothing
+```
+
+## `trigger()` and `dispatchEvent()`
+
+This function is used to trigger an event on an EventTarget which will cause all listeners to run.
+
+> Note: if 'click' is in `EventTarget.allowedEvents_`, trigger will attempt to call the
+>       `onClick` function if it exists.
+
+```js
+var foo = new EventTarget();
+var handleBar = function() {
+  console.log('bar was triggered');
+};
+
+foo.on('bar', handleBar);
+foo.trigger('bar');
+// logs 'bar was triggered'
+
+foo.trigger('bar');
+// logs 'bar was triggered'
+
+foo.trigger('foo');
+// does nothing
+```